Note: Before using this information, be sure to read the
general information under Notices.
|
This edition applies to IBM® Rational® Developer for System z® Version 9.1.1 (program number 5724-T07) and to all subsequent releases and modifications until otherwise indicated in new editions.
Order publications by phone or fax. IBM Software Manufacturing Solutions takes publication orders between 8:30 a.m. and 7:00 p.m. eastern standard time (EST). The phone number is (800) 879-2755. The fax number is (800) 445-9269. Faxes should be sent Attn: Publications, 3rd floor.
You can also order publications through your IBM representative or the IBM branch office serving your locality. Publications are not stocked at the address below.
IBM welcomes your comments. You can send your comments by mail to the following address:
IBM Corporation
Attn: Information Development Department 53NA
Building 501 P.O. Box 12195
Research Triangle Park NC 27709-2195
USA
You can fax your comments to: 1-800-227-5088 (US and Canada)
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you.
© Copyright IBM Corporation 2000, 2014
Note to U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
This document gives background information for various configuration tasks of IBM Rational Developer for System z itself and other z/OS® components and products (such as WLM and CICS®).
The information in this document applies to all IBM Rational Developer for System z Version
9.1.1 packages.
For the most up-to-date versions of this document, see the IBM Rational Developer for System z Host Configuration Reference Guide (SC14-7290) available at http://www-05.ibm.com/e-business/linkweb/publications/servlet/pbi.wss?CTY=US&FNC=SRX&PBL=SC14-7290.
For the most up-to-date versions of the complete documentation, including installation instructions, white papers, podcasts, and tutorials, see the library page of the IBM Rational Developer for System z website (http://www-01.ibm.com/software/sw-library/en_US/products/Z964267S85716U24/).
This document is intended for system programmers configuring
and tuning IBM Rational Developer for System z Version
9.1.1.
While the actual configuration steps are described in another publication, this publication lists in detail various related subjects, such as tuning, security setup, and more. To use this document, you must be familiar with the z/OS UNIX System Services and MVS™ host systems.
This section summarizes the changes for IBM Rational Developer for System z Version
9.1.1 Host Configuration Reference, SC14-7290-08 (updated December
2014).
Technical changes or additions to the text and illustrations are indicated by a vertical line to the left of the change.
This document contains information previously presented in IBM Rational Developer for System z Version 9.1.1 Host Configuration Reference, SC14-7290-07.
This document contains information previously presented in IBM Rational Developer for System z Version 9.0.1 Host Configuration Reference, SC14-7290-06.
This document contains information previously presented in IBM Rational Developer for System z Version 9.0.1 Host Configuration Reference, SC14-7290-05.
New information:
This document contains information previously presented in IBM Rational Developer for System z Version 8.5.1 Host Configuration Reference, SC14-7290-03.
This document contains information previously presented in IBM Rational Developer for System z Version 8.5 Host Configuration Reference, SC14-7290-02.
This document contains information previously presented in IBM Rational Developer for System z Version 8.0.3 Host Configuration Reference, SC14-7290-01.
This document contains information previously presented in IBM Rational Developer for System z Version 8.0.1 Host Configuration Reference , SC14-7290-00.
This section summarizes the information presented in this document.
The Developer for System z host consists of several components that interact to give the client access to the host services and data. Understanding the design of these components can help you make the correct configuration decisions.
Developer for System z provides mainframe access to users on a non-mainframe workstation. Validating connection requests, providing secure communication between the host and the workstation, and authorizing and auditing activity are therefore important aspects of the product configuration.
Developer for System z uses TCP/IP to provide mainframe access to users on a non-mainframe workstation. It also uses TCP/IP for communication between various components and other products.
Unlike traditional z/OS applications, Developer for System z is not a monolithic application that can be identified easily to Workload Manager (WLM). Developer for System z consists of several components that interact to give the client access to the host services and data. Some of these services are active in different address spaces, resulting in different WLM classifications.
RSE (Remote Systems Explorer) is the core of Developer for System z. To manage the connections and workloads from the clients, RSE is composed of a daemon address space, which controls thread pooling address spaces. The daemon acts as a focal point for connection and management purposes, while the thread pools process the client workloads.
This makes RSE a prime target for tuning the Developer for System z setup. However, maintaining hundreds of users, each using 17 or more threads, a certain amount of storage, and possibly one or more address spaces requires proper configuration of both Developer for System z and z/OS.
z/OS is a highly customizable operating system, and (sometimes small) system changes can have a huge impact on the overall performance. This chapter highlights some of the changes that can be made to improve the performance of Developer for System z.
This chapter contains information useful for a CICS Transaction Server administrator.
This chapter assists you with enhancing Developer for System z by writing exit routines.
This chapter assists you with mimicking a TSO logon procedure by adding DD statements and data sets to the TSO environment in Developer for System z.
There are times that you want multiple instances of Developer for System z active on the same system, for example, when testing an upgrade. However, some resources such as TCP/IP ports cannot be shared, so the defaults are not always applicable. Use the information in this chapter to plan the coexistence of the different instances of Developer for System z, after which you can use this configuration guide to customize them.
This section is provided to assist you with some common problems that you may encounter when setting up Secure Socket Layer (SSL), or during checking or modifying an existing setup. This section also provides a sample setup to support users authenticating themselves with an X.509 certificate.
This section is provided to assist you with some common problems that you may encounter when setting up TCP/IP, or during checking or modifying an existing setup.
The Developer for System z host consists of several components that interact to give the client access to the host services and data. Understanding the design of these components can help you make the correct configuration decisions.
The description in the previous paragraph and list shows the central role assigned to RSE. With few exceptions, all client communication goes through RSE. This allows for easy security related network setup, as only a limited set of ports are used for client-host communication.
To manage the connections and workloads from the clients, RSE is composed of a daemon address space, which controls thread pooling address spaces. The daemon acts as a focal point for connection and management purposes, while the thread pools process the client workloads. Based upon the values defined in the rsed.envvars configuration file, and the amount of actual client connections, multiple thread pool address spaces can be started by the daemon.
Figure 2 shows a basic view of resource usage (processes and storage) by RSE.
RSE is a Java™ application, which means that it is active in the z/OS UNIX environment. This allows for easy porting to different host platforms and straightforward communication with the Developer for System z client, which is also a Java application (based on the Eclipse framework). Therefore, basic knowledge of how z/OS UNIX and Java work is very helpful when you try to understand Developer for System z.
In z/OS UNIX, a program runs in a process, which is identified by a PID (Process ID). Each program is active in its own process, so invoking another program creates a new process. The process that started a process is referenced with a PPID (Parent PID), the new process is called a child process. The child process can run in the same address space or it can be spawned (created) in a new address space. A new process that runs in the same address space can be compared to executing a command in TSO, while the spawning one in a new address space is similar to submitting a batch job.
Note that a process can be single- or multi-threaded. In a multi-threaded application (such as RSE), the different threads compete for system resources as if they were separate address spaces (with less overhead).
RSE is capabable of running in 31-bit or 64-bit addressing mode, resulting in different storage limits. In 31-bit mode, the available storage is limited to 2 GB, while in 64-bit mode, there is no limit, unless specified in SYS1.PARMLIB.
Java applications, such as RSE, do not allocate storage directly, but use Java memory management services. These services, like allocating storage, freeing storage, and garbage collection, work within the limits of the Java heap. The minimum and maximum size of the heap is defined (implicitly or explicitly) during Java startup. When running in 64-bit mode, Java will attempt to allocate the heap above the 2 GB bar, freeing up space below the bar.
This implies that getting the most out of the available address space size is a balancing act of defining a large heap size while leaving enough room for z/OS to store a variable amount of system control blocks (dependent on the number of active threads).
Figure 3 shows a basic overview of the owner of the security credentials used for various Developer for System z tasks.
The ownership of a task can be divided into two sections. Started tasks are owned by the user ID that is assigned to the started task in your security software. All other tasks, with the RSE thread pools (RSEDx) as exception, are owned by the client user ID.
Figure 3 shows the Developer for System z started tasks (DBGMGR, JMON, and RSED), and sample started tasks and system services that Developer for System z communicates with. Application Deployment Manager (ADM) is active inside a CICS region. The USS REXEC tag represents the z/OS UNIX REXEC (or SSH) service.
RSE daemon (RSED) creates one or more RSE thread pool address spaces (RSEDx) to process client requests. Each RSE thread pool supports multiple clients and is owned by the same user as the RSE daemon. Each client has his own threads inside a thread pool, and these threads are owned by the client user ID.
Depending on actions done by the client, one or more additional address spaces can be started, all owned by the client user ID, to perform the requested action. These address spaces can be an MVS batch job, an APPC transaction, or a z/OS UNIX child process. Note that a z/OS UNIX child process is active in a z/OS UNIX initiator (BPXAS), and the child process shows up as a started task in JES.
The creation of these address spaces is most often triggered by a user thread in a thread pool, either directly or by using system services like ISPF. But the address space could also be created by a third party. For example, z/OS UNIX REXEC or SSH are involved when starting builds in z/OS UNIX.
The user-specific address spaces end at task completion or when an inactivity timer expires. The started tasks remain active. The address spaces listed in Figure 3 remain in the system long enough to be visible. However, you should be aware that due to the way z/OS UNIX is designed, there are also several short-lived temporary address spaces.
The previous description shows the thread-oriented design of RSE. Instead of starting an address space per user, multiple users are serviced by a single thread pool address space. Within the thread pool, each miner (a user specific service) is active in its own thread with the user's security context assigned to it, ensuring a secure setup. This design accommodates large number of users with limited resource usage, but does imply that each client will use multiple threads (17 or more, depending on the performed tasks).
The usage of PassTickets for all z/OS services that require authentication allows Developer for System z to invoke these services without storing the password or constantly prompting the user for it. Use of PassTickets for all z/OS services also allows for alternative authentication methods during logon, such as one-time passwords and X.509 certificates.
Developer for System z supports multiple methods to start a CARMA server. Each method has benefits and drawbacks. Developer for System z also provides multiple Repository Access Managers (RAMs), which can be divided into two groups, production RAMs and sample RAMs. Various combinations of RAMs and server startup methods are available as a preconfigured setup.
All server startup methods share a common configuration file, CRASRV.properties, which (among other things) specifies which startup method will be used.
The "CRASTART" method starts the CARMA server as a subtask within RSE. It provides a very flexible setup by using a separate configuration file that defines data set allocations and program invocations needed to start a CARMA server. This method provides the best performance and uses the fewest resources, but requires that module CRASTART is located in LPA.
RSE invokes load module CRASTART, which uses the definitions in crastart*.conf to create a valid environment to execute batch TSO and ISPF commands. Developer for System z uses this environment to run the CARMA server, CRASERV. Developer for System z provides multiple crastart*.conf files, each preconfigured for a specific RAM.
The "batch submit" method starts the CARMA server by submitting a job. This is the default method used in the provided sample configuration files. The benefit of this method is that the CARMA logs are easily accessible in the job output. It also allows the use of custom server JCL for each developer, which is maintained by the developer himself. However, this method uses one JES initiator per developer starting a CARMA server.
RSE invokes CLIST CRASUB*, which in turn submits an embedded JCL to create a valid environment to execute batch TSO and ISPF commands. Developer for System z uses this environment to run the CARMA server, CRASERV. Developer for System z provides multiple CRASUB* members, each preconfigured for a specific RAM.
With the single-server setup of Developer for System z, where multiple users are assigned to a single thread pool address space, z/OS lost the ability to track who owns a lock on a data set or member with the DISPLAY GRS,RES=(*,dataset*) operator command. System commands stop at address space level, which is the thread pool.
To address this problem, Developer for System z provides the MODIFY rsed APPL=DISPLAY OWNER,DATASET=dataset operator command, as described in "Operator commands" in the Host Configuration Guide (SC23-7658). The operator command can resolve all data set and member locks done by RSE users, as well as locks done by other products, such as ISPF.
Under normal circumstances, a data set or member is locked when the client opens it in edit mode, and freed when the client closes the edit session.
Certain error conditions can prevent this mechanism from working as designed. In this case, the user holding the lock can be canceled using RSE’s modify cancel operator command, as described in "Operator commands" in the Host Configuration Guide (SC23-7658). Active data set locks belonging to this user are freed during the process.
Figure 8 shows an overview of the z/OS UNIX directories used by Developer for System z. The following list describes each directory touched by Developer for System z, how the location can be changed, and who maintains the data within.
The data in /var/rdz/pushtoclient/ is maintained by non-system administrators, such as project managers, who might not have many update privileges in z/OS UNIX. Therefore, it is important to understand how z/OS UNIX sets access permissions during file creation to ensure you have workable but secure setup.
UNIX standards dictate that permissions can be set for three types of users: owner, group, and other. Read, write, and execute permissions can be set for each type individually.
Each site can set their own default access permission mask, but a common mask allows read and write permission to the owner, and read permission to group and other.
Data in /var/rdz/pushtoclient/ is created using the access permission mask defined in the file.permission directive of pushtoclient.properties. The default value allows read and write permission for owner and group, and read permission for other. All have execute permission. The final access permissions should allow read and execute for all, and write for the Developer for System z client administrators that maintain the data.
Data in /var/rdz/pushtoclient/projects/ is created using no specific access permission mask. The final access permissions should allow read permission for all, and write permission for the project managers that maintain the data.
ADDGROUP RDZPROJ OMVS(GID(1200))
CONNECT IBMUSER GROUP(RDZPROJ)
ALTUSER IBMUSER DFLTGRP(RDZPROJ)
ls -lR /var/rdz/pushtoclient/
chown –R IBMUSER /var/rdz/pushtoclient/
chgrp -R RDZPROJ /var/rdz/pushtoclient/
chmod -R 775 /var/rdz/pushtoclient/
In the following scenario, all the development project managers, a team of three, are tasked with being a Developer for System z client administrator.
# chmod 775 /var/rdz/pushtoclient
# ls -ld /var/rdz/pushtoclient
drwxrwxr-x 2 IBMUSER SYS1
/var/rdz/pushtoclient
# chgrp RDZPROJ /var/rdz/pushtoclient
# ls –ld /var/rdz/pushtoclient
drwxrwxr-x 2 IBMUSER RDZPROJ
/var/rdz/pushtoclient
This concludes the setup required to limit /var/rdz/pushtoclient write permissions to the systems programmer (IBMUSER) and the project managers (RDZPROJ).
Developer for System z provides mainframe access to users on a non-mainframe workstation. Validating connection requests, providing secure communication between the host and the workstation, and authorizing and auditing activity are therefore important aspects of the product configuration.
The security mechanisms used by Developer for System z servers and services rely on the data sets and file systems it resides in being secure. This implies that only trusted system administrators should be able to update the program libraries and configuration files.
The following topics are covered in this chapter:
Refer to Understanding Developer for System z to learn about basic Developer for System z design concepts.
Developer for System z supports multiple ways to authenticate a user ID provided by a client upon connection.
The client provides a user ID and matching password upon connection. The user ID and password are used to authenticate the user with your security product.
Based upon a unique token, a one-time password can be generated by a third-party product. One-time passwords improve your security setup as the unique token cannot be copied and used without the user's knowledge, and an intercepted password is useless because it is valid only once.
The client provides a user ID and the one-time password upon connection, which is used to authenticate the user ID with the security exit provided by the third party. This security exit is expected to ignore the PassTickets used to satisfy authentication requests during normal processing. The PassTickets must be processed by your security software.
The client provides a user ID and matching pass phrase upon connection. The user ID and pass phrase are used to authenticate the user with your security product.
A third party can provide one or more X.509 certificates that can be used for authenticating a user. When stored on secure devices, X.509 certificates combine a secure setup with ease of use for the user (no user ID or password needed).
Upon connection, the client provides a selected certificate, and optionally a selected extension, which is used to authenticate the user ID with your security product.
Client authentication is done by RSE daemon (or REXEC/SSH) as part of the client's connection request. Once the user is authenticated, self-generated PassTickets are used for all future authentication requests, including the automatic logon to JES Job Monitor.
In order for JES Job Monitor to validate the user ID and PassTicket presented by RSE, JES Job Monitor must be allowed to evaluate the PassTicket. This implies the following:
Client authentication is done by RSE daemon (or REXEC/SSH) as part of the client's connection request. After the user is authenticated, self-generated PassTickets are used for all future authentication requests, including the automatic logon to Debug Manager.
In order for Debug Manager to validate the user ID and PassTicket presented by RSE, Debug Manager must be allowed to evaluate the PassTicket. This implies that load module AQEZPCM, by default located in load library FEK.SFEKAUTH, must be APF-authorized.
When a client-based Debug Engine connects to the Debug
Manager, it must present a valid security token for authentication.
Developer for System z relies on third-party products, such as the TN3270 server, to provide some services. See the related product documentation for connection security options.
The system programmer can specify the ports on which the RSE server can communicate with the client. By default, any available port is used. This range of ports has no connection with the RSE daemon port.
All external Developer for System z data streams that pass through RSE can be encrypted using Secure Socket Layer (SSL) or Transport Layer Security (TLS). The use of encrypted communication is controlled by the settings in the ssl.properties configuration file, as described in SSL/TLS encrypted communication. The DSTORE_SSL_ALGORITHM variable in the _RSE_JAVAOPTS directive of rsed.envvars lets you choose between SSL and its successor TLS as encryption method, as documented in "Defining extra Java startup parameters with _RSE_JAVAOPTS" in the Host Configuration Guide (SC23-7658).
The Integrated Debugger Engine on the client connects to the Debug Manager on the host. The usage of SSL or TLS is controlled by an Application Transparent TLS (AT-TLS) policy.
The Host Connect Emulator on the client connects to a TN3270 server on the host. The use of SSL or TLS is controlled by TN3270, as documented in the Communications Server IP Configuration Guide (SC31-8775).
Remote (host-based) actions in z/OS UNIX subprojects use an REXEC or SSH server on the host. SSH communication is always encrypted using SSL.
The Application Deployment Manager client uses the CICS TS Web Service or the RESTful interface to invoke the Application Deployment Manager host services. The usage of SSL is controlled by CICS TS, as documented in RACF Security Guide for CICS TS.
Developer for System z supports Port Of Entry (POE) checking, which allows host access only to trusted TCP/IP addresses. The usage of POE is controlled by the definition of specific profiles in your security software and the enable.port.of.entry directive in rsed.envvars, as described in Port Of Entry (POE) checking.
Note that activating POE will impact other TCPIP applications that support POE checking, such as INETD.
After logon, PassTickets are used to establish thread security within the RSE server. This feature cannot be disabled. PassTickets are system generated passwords with a lifespan of about 10 minutes. The generated PassTickets are based upon the DES encryption algorithm, the user ID, the application ID, a time and date stamp, and a secret key. This secret key is a 64 bit number (16 hex characters) that must be defined to your security software. For additional security, z/OS security software handles PassTickets by default as single-use passwords.
The actual password of the client is no longer needed after initial authentication because SAF-compliant security products can evaluate both PassTickets and regular passwords. RSE server generates and uses a PassTicket each time a password is required, resulting in a (temporary) valid password for the client.
Using PassTickets allows RSE to set up a user-specific security environment at will, without the need of storing all user IDs and passwords in a table, which could be compromised. It also allows for client authentication methods that do not use reusable passwords, such as X.509 certificates.
Security profiles in the APPL and PTKTDATA classes are required to be able to use PassTickets. These profiles are application specific and thus do not impact your current system setup.
PassTickets being application specific implies that both RSE and JES Job Monitor must use the same application ID (APPLID). By default both servers use FEKAPPL as APPLID, but this can be changed by the APPLID directive in rsed.envvars for RSE and in FEJJCNFG for JES Job Monitor.
You should not use OMVSAPPL as application ID, because it will open the secret key to most z/OS UNIX applications. You should also not use the default MVS application ID, which is MVS followed by the system's SMF ID, because this will open the secret key to most MVS applications (including user batch jobs).
The smallest unit of a PassTicket timestamp is 1 second. This implies that all PassTickets generated within a single second by the same application for the same user ID will be identical. This, combined with z/OS security software handling PassTickets as single-use passwords, causes a problem for Developer for System z during logon, as multiple PassTickets will be required within a second. Therefore, Developer for System z requires setting a flag in the PassTicket definitions that allows the generated PassTickets to be reused.
Attention: The client connection
request will fail if PassTickets are not set up correctly.
|
Developer for System z supports audit logging of actions that are managed by the RSE daemon. The audit logs are stored as text files in the daemon log directory, using the CSV (Comma Separated Value) format.
The modify switch operator command can be used to manually switch to a new audit log file, as documented in "Operator commands" in the Host Configuration Guide (SC23-7658).
A warning message is sent to the console when the file system holding the audit log files is running low on free space. This console message (FEK103E) is repeated regularly until the low space issue is resolved.
A new audit log file is started after a predetermined time or when the modify switch operator command is issued. The old log file is saved as audit.log.yyyymmdd.hhmmss, where yyyymmdd.hhmmss is the date/timestamp when this log was closed. The system date/timestamp assigned to the file indicates the creation of the log file. The combination of the two dates shows the time period covered by this audit log file.
The audit.action* directives in rsed.envvars allow you to specify a user exit (z/OS UNIX shell script, z/OS UNIX REXX, or z/OS UNIX program) which will be invoked by RSE when an audit log is closed. This user exit can then process the data within the audit log.
Audit log files have permission bit mask 640 (-rw-r-----), if not changed by the audit.log.mode directive in rsed.envvars. This means that the owner (RSE daemon z/OS UNIX uid) has read and write access, and the owner’s (default) group has read access. All other access attempts are denied, unless it is done by a super user (UID 0) or somebody with sufficient permission to the SUPERUSER.FILESYS profile in the UNIXPRIV security class.
yyyy/mm/dd hh:mm:ss.sss,userid,action,dataset_name[,returncode]
[,additional_information]]
yyyy/mm/dd hh:mm:ss.sss,userid,action,dataset_name,returncode,create%nmodify%n…
Developer for System z allows clients access to the JES spool through the JES Job Monitor. The server provides basic access limitations, which can be extended with the standard spool file protection features of your security product. Operator actions (Hold, Release, Cancel, and Purge) against spool files are done through an EMCS console, for which conditional permits must be set up.
JES Job Monitor does not provide Developer for System z users full operator access to the JES spool. Only the Hold, Release, Cancel, and Purge commands are available, and by default, only for spool files owned by the user. The commands are issued by selecting the appropriate option in the client menu structure (there is no command prompt). The scope of the commands can be widened, using security profiles to define for which jobs the commands are available.
Similar to the SDSF SJ action character, JES Job Monitor also supports the Show JCL command to retrieve the JCL that created the selected job output, and show it in an editor window. JES Job Monitor retrieves the JCL from JES, making it a useful function for situations in which the original JCL member is not easily located.
Action | JES2 | JES3 |
---|---|---|
Hold | $Hx(jobid) with x = {J, S or T} |
*F,J=jobid,H |
Release | $Ax(jobid) with x = {J, S or T} |
*F,J=jobid,R |
Cancel | $Cx(jobid) with x = {J, S or T} |
*F,J=jobid,C |
Purge | $Cx(jobid),P with x = {J, S or T} |
*F,J=jobid,C |
Show JCL | not applicable | not applicable |
The available JES commands listed in Table 1 are by default limited to jobs owned by the user. This can be changed with the LIMIT_COMMANDS directive, as documented in "FEJJCNFG, JES Job Monitor configuration file" in the Host Configuration Guide (SC23-7658).
Job owner | ||
---|---|---|
LIMIT_COMMANDS | User | Other |
USERID (default) | Allowed | Not allowed |
LIMITED | Allowed | Allowed only if explicitly permitted by security profiles |
NOLIMIT | Allowed | Allowed if permitted by security profiles or when the JESSPOOL class is not active |
JES uses the JESSPOOL class to protect SYSIN/SYSOUT data sets. Similar to SDSF, JES Job Monitor extends the use of the JESSPOOL class to protect job resources as well.
Command | JESSPOOL profile | Required access |
---|---|---|
Hold | nodeid.userid.jobname.jobid | ALTER |
Release | nodeid.userid.jobname.jobid | ALTER |
Cancel | nodeid.userid.jobname.jobid | ALTER |
Purge | nodeid.userid.jobname.jobid | ALTER |
Show JCL | nodeid.userid.jobname.jobid.JCL | READ |
nodeid | NJE node ID of the target JES subsystem |
userid | Local user ID of the job owner |
jobname | Name of the job |
jobid | JES job ID |
If the JESSPOOL class is not active, then there is different behavior for the LIMITED and NOLIMIT value of LIMIT_COMMANDS, as described in the "LIMIT_COMMANDS command permission matrix table" in "FEJJCNFG, JES Job Monitor Configuration file" in the Host Configuration Guide (SC23-7658). The behavior is identical when JESSPOOL is active, since the class, by default, denies permission if a profile is not defined.
The second phase of JES spool command security, after specifying the permitted targets, includes the permits needed to actually execute the operator command. This execution authorization is enforced by the z/OS and JES security checks.
Note that Show JCL is not an operator command such as the other JES Job Monitor commands (Hold, Release, Cancel, and Purge), so the limitations in the next list do not apply because there is no further security check.
JES Job Monitor issues all JES operator commands requested by a user through an extended MCS (EMCS) console, whose name is controlled with the CONSOLE_NAME directive, as documented in "FEJJCNFG, JES Job Monitor configuration file" in the Host Configuration Guide (SC23-7658).
JES Job Monitor allows you to define how much authority is granted to the EMCS console with the LIMIT_CONSOLE directive, as documented in "FEJJCNFG, JES Job Monitor configuration file" in the Host Configuration Guide (SC23-7658).
LIMIT_CONSOLE | Active profile in OPERCMDS class | No active profile in OPERCMDS class |
---|---|---|
LIMITED (default) | Allowed, if permitted by security profile | Not allowed |
NOLIMIT | Allowed, if permitted by security profile | Allowed |
Assuming the identity of the JES Job Monitor server by creating a JMON console from a TSO session is prevented by your security software. Even though the console can be created, the point of entry is different (JES Job Monitor versus TSO). JES commands issued from this console will fail the security check, if your security is set up as documented in this publication and the user does not have authority to JES commands through other means.
Refer to Security Server RACF Security Administrator's Guide (SA22-7683) for more information on operator command protection.
JES Job Monitor allows browse access to all spool files by default. This can be changed with the LIMIT_VIEW directive, as documented in "FEJJCNFG, JES Job Monitor configuration file" in the Host Configuration Guide (SC23-7658).
Job owner | ||
---|---|---|
LIMIT_VIEW | User | Other |
USERID | Allowed | Not allowed |
NOLIMIT (default) | Allowed | Allowed if permitted by security profiles or when the JESSPOOL class is not active |
To limit users to their own jobs on the JES spool, define the "LIMIT_VIEW=USERID" statement in the JES Job Monitor configuration file, FEJJCNFG. If the users need access to a wider range of jobs, but not all, use the standard spool file protection features of your security product, such as the JESSPOOL class.
When defining further protection, keep in mind that JES Job Monitor uses SAPI (SYSOUT application program interface) to access the spool. This implies that the user needs at least UPDATE access to the spool files, even for browse functionality. This requisite does not apply if you run z/OS 1.7 (z/OS 1.8 for JES3) or higher. Here READ permission is sufficient for browse functionality.
Refer to Security Server RACF Security Administrator's Guide (SA22-7683) for more information on JES spool file protection.
External (client-host) communication using RSE can be encrypted using SSL (Secure Socket Layer) or Transport Layer Security (TLS). This feature is disabled by default and is controlled by the settings in ssl.properties. Refer to "(Optional) ssl.properties, RSE SSL encryption" in the Host Configuration Guide (SC23-7658).
RSE daemon and RSE server support different mechanisms to store certificates due to architectural differences between the two. This implies that SSL definitions and certificates are required for both RSE daemon and RSE server. A shared certificate can be used if RSE daemon and RSE server use the same certificate management method.
Certificate storage | Created and managed by | RSE daemon | RSE server |
---|---|---|---|
key ring | SAF compliant security product | supported | supported |
key database | z/OS UNIX's gskkyman | supported | / |
key store | Java's keytool | / | supported |
SAF-compliant key rings can store the certificate's private key either in the security database or by using ICSF (Integrated Cryptographic Service Facility), the interface to System z cryptographic hardware.
ICSF is recommended for the storage of the private keys associated with digital certificates, because it is a more secure solution than non-ICSF private key management. ICSF ensures that private keys are encrypted under the ICSF master key and that access to them is controlled by general resources in the CSFKEYS and CSFSERV security classes. In addition, operational performance is improved because ICSF utilizes the hardware Cryptographic Coprocessor. See Cryptographic Services ICSF Administrator's Guide (SA22-7521) for more details about ICSF and how to control who can use cryptographic keys and services.
RSE daemon uses System SSL functions to manage SSL encrypted communications. This implies that SYS1.SIEALNKE must be program controlled by your security software and available to RSE via LINKLIST or the STEPLIB directive in rsed.envvars.
The DSTORE_SSL_ALGORITHM variable in the _RSE_JAVAOPTS directive of rsed.envvars lets you choose between SSL and its successor TLS as encryption method, as documented in "Defining extra Java startup parameters with _RSE_JAVAOPTS" in the Host Configuration Guide (SC23-7658).
See Setting up SSL and X.509 authentication for more details on activating SSL for Developer for System z.
By default, RSE daemon relies on System SSL defaults for supported encryption protocols and cipher suite definitions. You can alter these defaults by specifying GSK_PROTOCOL_* and GSK_V3_CIPHER_SPECS* environment variables in rsed.envvars. For information on these environment variables, see Cryptographic Services System SSL Programming (SC24-5901).
TTLSRule RDz_Debug_Manager
{
LocalPortRange 5335
Direction Inbound
TTLSGroupActionRef grp_Production
TTLSEnvironmentActionRef RDz_Debug_Manager
}
TTLSEnvironmentAction RDz_Debug_Manager
{
HandshakeRole Server
TTLSKeyRingParms
{
Keyring dbgmgr.racf # Keyring must be owned by the Debug Manager
}
}
TTLSGroupAction grp_Production
{
TTLSEnabled On
Trace 2
}
RSE daemon supports users authenticating themselves with an X.509 certificate. Using SSL encrypted communication is a prerequisite for this function, as it is an extension to the host authentication with a certificate used in SSL.
RSE daemon starts the client authentication process by validating the client certificate. Some key aspects that are checked are the dates the certificate is valid and the trust-worthiness of the Certificate Authority (CA) used to sign the certificate. Optionally, a (third party) Certificate Revocation List (CRL) can also be consulted.
After RSE daemon validates the certificate, it is processed for authentication. The certificate is passed on to your security product for authentication, unless rsed.envvars directive enable.certificate.mapping is set to false, at which point RSE daemon will do the authentication.
If successful, the authentication process will determine the user ID to be used for this session, which is then tested by RSE daemon to ensure it is usable on the host system where RSE daemon is running.
The last check (which is done for every authentication mechanism, not just X.509 certificates) verifies that the user ID is allowed to use Developer for System z.
If you are familiar with the SSL security classifications used by TCP/IP, the combination of these validation steps match the “Level 3 Client authentication” specifications (the highest available).
Part of the certificate validation process includes checking that the certificate was signed by a Certificate Authority (CA) you trust. In order to do so, RSE daemon must have access to a certificate that identifies the CA.
When using the gskkyman key database for your SSL connection, the CA certificate must be added to the key database.
Refer to Security Server RACF Command Language Reference (SA22-7687) for more information on the RACDCERT command.
Attention: If you rely on RSE daemon instead of your security software to authenticate a user you must be cautious not to mix CAs with a TRUST and HIGHTRUST status in your SAF key ring or gskkyman key database. RSE daemon is not able to differentiate between the two, so certificates signed by a CA with TRUST status will be valid for user ID authentication purposes. |
Refer to the Cryptographic Services System Secure Sockets Layer Programming (SC24-5901) for more information on these and other environment variables used by z/OS System SSL.
RACF performs several checks to authenticate a certificate and return the associated user ID. Note that other security products might do this differently. Refer to your security product documentation for more information on the initACEE function used to do the authentication (query mode).
RACDCERT ID(userid) ADD(dsn) TRUST WITHLABEL('label')
id-ce-hostIdMappings OBJECT IDENTIFIER::= {1 3 18 0 2 18 1}
HostIdMappings::= SET OF HostIdMapping
HostIdMapping::= SEQUENCE{
hostName IMPLICIT[1] IA5String,
subjectId IMPLICIT[2] IA5String,
proofOfIdPossession IdProof OPTIONAL
}
IdProof::= SEQUENCE{
secret OCTET STRING,
encryptionAlgorithm OBJECT IDENTIFIER
}
Refer to Security Server RACF Security Administrator’s Guide (SA22-7683) for more information on X.509 certificates, how they are managed by RACF, and how to define certificate name filters. Refer to Security Server RACF Command Language Reference (SA22-7687) for more information on the RACDCERT command.
Developer for System z can do basic X.509 certificate authentication without relying on your security product. Authentication done by RSE daemon requires a user ID and host name to be defined in a certificate extension, and is only activated if the enable.certificate.mapping directive in rsed.envvars is set to FALSE.
This function is intended to be used if your security product does not support authenticating a user based upon an X.509 certificate, or if your certificate would fail the test(s) done by your security product (for example, the certificate has a faulty identifier for the HostIdMappings extension and there is no name filter or definition in DIGTCERT).
The client will query the user for the extension identifier (OID) to use, which is by default the HostIdMappings OID, {1 3 18 0 2 18 1}.
RSE daemon will extract the user ID and host name from it using the format of the HostIdMappings extension. This format is described in Authentication by your security software .
Attention: It is up to the security
administrator to ensure that all CAs known to RSE daemon are highly
trusted, because RSE daemon cannot check if the one who signed the
client certificate is highly trusted or just trusted. See Certificate Authority (CA) validation for more information
on accessible CA certificates.
|
Refer to Communications Server IP Configuration Guide (SC31-8775) for more information on network access control using POE checking.
Developer for System z clients version 8.5.1 and higher can check access authorization to SAF security profiles, and based on the result enable or disable the related function for the user.
Developer for System z verifies access permits to the profiles listed in Table 7 to determine which options should enabled or disabled for the user.
FACILITY profile | Fixed length | Required access | Result |
---|---|---|---|
FEK.USR.OFF.REMOTECOPY.MVS.sysname | 27 | READ | Client disables copy and related functions for MVS data sets |
The sysname value matches the system name of the target system.
The "Fixed length" column documents the length of the fixed part of the related security profile.
By default, Developer for System z expects the FEK.* profiles to be in the FACILITY security class. Note that profiles in the FACILITY class are limited to 39 characters. If the sum of the length of the fixed profile part (FEK.USR.<key>) and the length of the site-specific profile part (sysname) exceeds this number, you can place the profiles in another class and instruct Developer for System z to use this class instead. To do so, uncomment _RSE_FEK_SAF_CLASS in rsed.envvars and provide the desired class name.
RDEFINE FACILITY (FEK.USR.OFF.REMOTECOPY.MVS.CDFMVS08) -
UACC(NONE) DATA('RATIONAL DEVELOPER FOR SYSTEM Z - CLIENT CONTROL')
PERMIT FEK.USR.OFF.REMOTECOPY.MVS.CDFMVS08 CLASS(FACILITY) -
ID(RESTRICT) ACCESS(READ)
SETROPTS RACLIST(FACILITY) REFRESH
When users have READ access to profile FEK.USR.OFF.REMOTECOPY.MVS.sysname, then their Developer for System z clients version 8.5.1 and higher will disable drag, copy, save-as, and work-offline actions for MVS data sets. The result is that the users can access the data sets on this system, but the users cannot create a local copy of a data set on their workstation. This helps prevent exposure of confidential information if the local workstation is lost or stolen.
Developer for System z clients version 8.0.1 and higher can pull client configuration files and upgrade information from the host when they connect, ensuring that all clients have common settings and that they are up-to-date.
Since version 8.0.3, the client administrator can create multiple client configuration sets and multiple client update scenarios to fit the needs of different developer groups. This allows users to receive a customized setup, based on criteria like membership of an LDAP group or permit to a security profile.
When using definitions in your security database as selection mechanism (the SAF value is specified for directives in pushtoclient.properties), Developer for System z verifies access permits to the profiles listed in Table 8 to determine which developer groups the user belongs to, and whether a user is allowed to reject updates.
FACILITY profile | Fixed length | Required access | Result |
---|---|---|---|
FEK.PTC.CONFIG.ENABLED. |
23 | READ | Client accepts configuration updates for the specified group |
FEK.PTC.PRODUCT. |
24 | READ | Client accepts product updates for the specified group |
FEK.PTC.REJECT.CONFIG. |
30 | READ | User can reject configuration updates |
FEK.PTC.REJECT.PRODUCT. |
31 | READ | User can reject product updates |
The devgroup value matches the group name assigned to a specific group of developers. Note that the group name is visible on Developer for System z clients.
The sysname value matches the system name of the target system.
The “Fixed length” column documents the length of the fixed part of the related security profile.
By default, Developer for System z expects the FEK.* profiles to be in the FACILITY security class. Note that profiles in the FACILITY class are limited to 39 characters. If the sum of the length of the fixed profile part (FEK.PTC.<key>) and the length of the site-specific profile part (sysname or sysname.devgroup) exceeds this number you can place the profiles in another class and instruct Developer for System z to use this class instead. To do so, uncomment _RSE_FEK_SAF_CLASS in rsed.envvars and provide the desired class name.
Note that the client administrator must be on the access list of the FEK.PTC.*.ENABLED.* profiles to define and manage the related push-to-client metadata. This implies that the profiles must be defined with (at least) the client administrator on the access list before push-to-client with group support can be implemented.
See “(Optional) pushtoclient.properties, Host-based client control” in the Host Configuration Guide (SC23-7658) for more information about enabling multiple group support. See Push-to-client considerations for more information about push-to-client concepts and implementation.
The log directories and log files created by Developer for System z have, by default, secure access permissions where only the owner has access (read and write). For server (and audit) logs, the owner is the RSED started task user ID. For user logs the owner is the user ID provided by the end user during logon. The log.file.mode directive in rsed.envvars can be used to set different access permissions. Note that the access permissions for audit files are controlled separately, and are set with the audit.log.mode directive in rsed.envvars.
Before writing to a log directory, Developer for System z will validate the file ownership, and will fail the write if a different user owns the file. This behavior is new in version 9.1.0, and might require you to alter an existing log file structure. The log.secure.mode directive in rsed.envvars can be used to disable the ownership check.
Sample JCL FEKPBITS can be used to convert access permissions and ownership of an existing log file infrastructure. FEKPBITS is located in FEK.#CUST.JCL, unless you specified a different location when you customized and submitted the FEK.SFEKSAMP(FEKSETUP) job. See "Customization setup" in the Host Configuration Guide (SC23-7658) for more details.
The RSED start task supports the MODIFY LOGS operator command to collect Developer for System z host logs and setup information. The collected data is placed in a z/OS UNIX file, $TMPDIR/feklogs%sysname.%jobname, where $TMPDIR is the value of the TMPDIR directive in rsed.envvars (default /tmp), %sysname is your z/OS system name and %jobname is the name of the RSED started task.
Developer for System z will query your security product for access permits to FEK.CMD.LOGS.** profiles to determine if the requestor is allowed to collect the specified logs. By default, the requestor is the RSED started task user ID, unless the OWNER option is specified. Only the requestor has access to the file holding the collected data.
FACILITY profile | Fixed length | Required access | Result |
---|---|---|---|
FEK.CMD.LOGS.AUDIT.jobname | 19 | READ | The requestor can collect audit logs of jobname |
FEK,CMD.LOGS.SERVER.jobname | 20 | READ | The requestor can collect server logs of jobname |
FEK,CMD.LOGS.USER.userid | 18 | READ | The requestor can collect user logs of userid |
FEK,CMD.LOGS.OWNER.userid | 19 | READ | The requestor is changed from RSED started task user ID to userid |
The jobname value matches the RSED started task name. The userid value matches a valid user ID.
The “Fixed length” column documents the length of the fixed part of the related security profile.
By default, Developer for System z expects the FEK.* profiles to be in the FACILITY security class. Note that profiles in the FACILITY class are limited to 39 characters. If the sum of the length of the fixed profile part (FEK.CMD.LOGS.<key>) and the length of the site-specific profile part (jobname or userid) exceeds this number you can place the profiles in another class and instruct Developer for System z to use this class instead. To do so, uncomment _RSE_FEK_SAF_CLASS in rsed.envvars and provide the desired class name.
Access violations are reported with console message FEK302E.
The following sample security definitions allow everyone to collect host logs, but only group SYSPROG can collect audit data:
RDEFINE FACILITY (FEK.CMD.LOGS.**) UACC(READ) -
DATA('RATIONAL DEVELOPER FOR SYSTEM Z - LOGS OPERATOR COMMAND')
RDEFINE FACILITY (FEK.CMD.LOGS.AUDIT.**) UACC(NONE) –
DATA('RATIONAL DEVELOPER FOR SYSTEM Z - LOGS OPERATOR COMMAND')
PERMIT FEK.CMD.LOGS.AUDIT.** CLASS(FACILITY) -
ID(SYSPROG) ACCESS(READ)
SETROPTS RACLIST(FACILITY) REFRESH
The MODIFY LOGS operator command uses the RSED started task user ID to collect host logs and setup information, and by default, user log files are created with secure file access permissions (only owner has access). To be able to collect secure user log files, the RSED started task user ID must be permitted to read them.
The OWNER argument of the MODIFY LOGS operator command results in the specified user ID becoming the owner of the collected data. In order to change ownership, the RSED started task user ID must be permitted to use the CHOWN z/OS UNIX service.
There are three ways these permissions can be provided to the RSED started task user ID. In order of preference, these are
The UNIXPRIV class holds profiles that allow a security administrator to selectively hand out special z/OS UNIX related permits, instead of granting all z/OS UNIX related permits with the super user approach.
Profile | Permit | Result |
---|---|---|
SUPERUSER.FILESYS | READ | User is allowed to read any file or directory. |
SUPERUSER.FILESYS.ACLOVERRIDE | READ | Permit is only required if ACLOVERRIDE is already defined. It allows the user to read any file or directory, regardless of ACL definitions. |
SUPERUSER.FILESYS.CHOWN | READ | User is allowed to change the owner of any file or directory. |
When the RSED started task user ID has READ permission to the BPX.SUPERUSER profile in the FACILITY class, it is able to temporarily make itself a z/OS UNIX super user, for whom z/OS UNIX file access permissions do not count.
When the RSED started task user ID has UID 0 specified in its OMVS segment, it is a z/OS UNIX super user, for whom z/OS UNIX file access permissions do not count. However, this approach is not advised since UID 0 is likely a shared UID, and it is advised to give the RSED started task user ID a unique UID due to other permissions granted to the ID. (For example, z/OS UNIX administrators require UID 0 for certain system management tasks.)
The optional Integrated Debugger requires that users
have sufficient access permits to specified security profiles. If
the user does not have the required permit, the debug session will
not start.
Developer for System z verifies access to the profiles listed in Table 10 to determine which debug permits are granted.
FACILITY profile | Required access | Result |
---|---|---|
AQE.AUTHDEBUG.STDPGM | READ | User is able to debug problem-state applications |
AQE.AUTHDEBUG.AUTHPGM | READ | User is able to debug problem-state and authorized applications |
RDEFINE FACILITY (AQE.AUTHDEBUG.STDPGM) -
UACC(NONE) DATA('RATIONAL DEVELOPER FOR SYSTEM Z – DEBUG PROBLEM-STATE')
PERMIT AQE.AUTHDEBUG.STDPGM CLASS(FACILITY) -
ID(RDZDEBUG) ACCESS(READ)
SETROPTS RACLIST(FACILITY) REFRESH
The optional Integrated Debugger is capable of debugging CICS transactions. See CICS transaction debugging for more details.
Developer for System z allows, through Application Deployment Manager, CICS administrators to control which CICS resource definitions are editable by the developer, their default values, and the display of a CICS resource definition by means of the CICS Resource Definition (CRD) server. Refer to CICSTS considerations for more information on the required CICS TS security definitions.
The CRD server repository VSAM data set holds all the default resource definitions and must therefore be protected against updates, but developers must be allowed to read the values stored here.
Developer for System z supplies multiple transactions that are used by the CRD server when defining and inquiring CICS resources. When the transaction is attached, CICS resource security checking, if enabled, insures that the user ID is authorized to run the transaction ID.
The Application Deployment Manager client uses CICS TS Web Services or the RESTful interface to invoke the CRD server. The usage of SSL for this communication is controlled by the CICS TS TCPIPSERVICE definition, as documented in RACF Security Guide for CICS TS.
The SCLM Developer Toolkit service offers optional security functionality for the Build, Promote, and Deploy functions.
If security is enabled for a function by the SCLM administrator, SAF calls are made to verify authority to execute the protected function with the caller’s or a surrogate user ID.
Refer to SCLM Developer Toolkit Administrator’s Guide (SC23-9801), for more information on the required SCLM security definitions.
The first time an address space instructs RACF to accesses a resource class that is not RACLISTed (stored in memory), like the DATASET class, RACF will retrieve and store all the related generic profiles in the user’s address space, in a list known as GATE (Generic Anchor Table Entry). Up to z/OS 1.12, RACF maintains four generic anchors for each address space and four for each MVS TCB that has its own ACEE. When all four are used up, RACF replaces the least recently referenced one when a new one comes in.
If your users frequently access more than four data set high-level qualifiers, the RSE thread pools (serving multiple users using threads with user-specific ACEEs) might experience GATE trashing as RACF has to rotate new entries through the available anchor slots.
In z/OS 1.12, RACF introduced the GENERICANCHOR option of the SET command, which allows you to increase the size of the table. This can be set system-wide or for each job name.
Developer for System z uses z/OS UNIX kernel services, such as pthread_security_np() and __passwd(), that use the InitACEE security service, resulting in “managed ACEE” security control blocks. A managed ACEE (Accessor Environment Element) is cached by your security product, and your security product will ignore certain changes, (such as password changes outside of Developer for System z) until the cache times out. (Timing out can take a few minutes.)
Refresh the managed ACEE cache after security changes to ensure that the new data is used by Developer for System z.
RACF can save ACEEs (Accessor Environment Elements) using VLF (Virtual Lookaside Facility) and retrieve them for later use. Developer for System z asks your security software to build multiple security environments (ACEEs) for the same user (one for each user-specific thread in the RSE thread pool), and can thus benefit from ACEE caching.
For more information on ACEE caching, see “ACEEs and VLF considerations” in the Security Server RACF System Programmer's Guide (SA22-7681).
There are several Developer for System z configuration files whose directives impact the security and audit setup. Based upon the information in this chapter, the security administrator and systems programmer can decide what the settings should be for the following directives.
Define against which jobs actions can be done (excluding browse and submit). For more information, see Actions against jobs - target limitations.
Define authority level of the EMCS console used for executing actions. For more information, see Actions against jobs - target limitations.
Define which spool files can be browsed. For more information, see Access to spool files.
Define whether JES Job Monitor can be accessed from outside this z/OS system. For more information, see section FEJJCNFG, JES Job Monitor configuration file in the Basic customization chapter of the Host Configuration Guide (SC23-7658).
Application ID used for PassTicket creation/validation. For more information, see Using PassTickets.
Security class holding FEK.** profiles. For more information, see Push-to-client developer groups and Altering client functions.
Deny users to save their host password on the client. For more information, see "Defining extra Java startup parameters with _RSE_JAVAOPTS" in the Host Configuration Guide (SC23-7658).
Timer to disconnect idle clients. For more information, see "Defining extra Java startup parameters with _RSE_JAVAOPTS" in the Host Configuration Guide (SC23-7658).
Application ID used for PassTicket creation/validation. For more information, see Using PassTickets.
Enable Port Of Entry checking. For more information, see Port Of Entry (POE) checking.
Select SSL or TLS as communication encryption method. For more information, see SSL/TLS encrypted communication.
Use your security product to authenticate users with an X.509 certificate. For more information, see Client authentication using X.509 certificates.
GSK_LDAP_SERVER=*
GSK_LDAP_PORT={389 | *}
GSK_LDAP_USER=*
GSK_LDAP_PASSWORD=*
Additional security checks for X.509 authentication. For more information, see (Optional) Query a Certificate Revocation List (CRL).
File access permission mask of the host log files and directories.
Additional security checks (like ownership) for host log files and directories.
Path leading to the audit log files. For more information, see Audit logging.
File access permission mask of the audit log files. For more information, see Audit logging.
(_RSE_JAVAOPTS) -Daudit.action.id=<userid>
z/OS UNIX based user exit that processes audit logs. For more information, see Audit logging.
Location of the RSE daemon certificate. For more information, see SSL/TLS encrypted communication.
Name of the RSE daemon certificate. For more information, see SSL/TLS encrypted communication.
Location of the RSE server certificate. For more information, see SSL/TLS encrypted communication.
Name of the RSE server certificate. For more information, see SSL/TLS encrypted communication.
Type of key store used (Java key store or SAF key ring). For more information, see SSL/TLS encrypted communication.
reject.config.updates={true | false | SAF | LDAP}
Host-based control of Developer for System z client configuration files. For more information, see Push-to-client considerations.
reject.product.updates={true | false | SAF | LDAP}
Host-based control of Developer for System z client product updates. For more information, see Push-to-client considerations.
Customize and submit the sample FEKRACF member, which has sample RACF and z/OS UNIX commands to create the basic security definitions for Developer for System z.
FEKRACF is located in FEK.#CUST.JCL, unless you specified a different location when you customized and submitted the FEK.SFEKSAMP(FEKSETUP) job. See "Customization setup" in the IBM Rational Developer for System z Host Configuration Guide for more details.
See the RACF Command Language Reference (SA22–7687), for more information about RACF commands.
The following sections describe the required steps, optional configuration, and possible alternatives.
Description |
|
Value |
---|---|---|
Developer for System z product high-level qualifier |
|
|
Developer for System z customization high-level qualifier |
|
|
Integrated Debugger started task name |
|
|
JES Job Monitor started task name |
|
|
RSE daemon started task name |
|
|
Application ID |
|
Attention: Some products, such as FTP, require being program controlled if "WHEN PROGRAM" is active. Test this program control before activating it on a production system. |
A RACF OMVS segment or equivalent that specifies a valid non-zero z/OS UNIX user ID (UID), home directory, and shell command must be defined for each user of Developer for System z. Their default group also requires an OMVS segment with a group ID.
When using the optional Integrated Debugger, the user ID under which the application being debugged is active, and its default group also requires a valid RACF OMVS segment or equivalent.
In the following sample RACF commands, replace the #userid, #user-identifier, #group-name, and #group-identifier placeholders with actual values:
ALTUSER #userid
OMVS(UID(#user-identifier) HOME(/u/#userid) PROGRAM(/bin/sh) NOASSIZEMAX)
The following sample RACF commands create the DBGMGR, JMON, and RSED started tasks, with protected user IDs (STCDBM, STCJMON, and STCRSE) and the STCGROUP group assigned to them. Replace the #group-id and #user-id-* placeholders with valid OMVS IDs.
ADDGROUP STCGROUP OMVS(AUTOGID)
DATA('GROUP WITH OMVS SEGMENT FOR STARTED TASKS')
ADDUSER STCDBM DFLTGRP(STCGROUP) NOPASSWORD NAME('RDZ – DEBUG MANAGER')
OMVS(AUTOUID HOME(/tmp) PROGRAM(/bin/sh) )
DATA('RATIONAL DEVELOPER FOR SYSTEM Z')
ADDUSER STCJMON DFLTGRP(STCGROUP) NOPASSWORD NAME('RDZ - JES JOBMONITOR')
OMVS(AUTOUID HOME(/tmp) PROGRAM(/bin/sh) )
DATA('RATIONAL DEVELOPER FOR SYSTEM Z')
ADDUSER STCRSE DFLTGRP(STCGROUP) NOPASSWORD NAME('RDZ - RSE DAEMON')
OMVS(AUTOUID HOME(/tmp) PROGRAM(/bin/sh) ASSIZEMAX(2147483647) )
DATA('RATIONAL DEVELOPER FOR SYSTEM Z')
RDEFINE STARTED DBGMGR.* DATA('RDZ – DEBUG MANAGER')
STDATA(USER(STCDBM) GROUP(STCGROUP) TRUSTED(NO))
RDEFINE STARTED JMON.* DATA('RDZ - JES JOBMONITOR')
STDATA(USER(STCJMON) GROUP(STCGROUP) TRUSTED(NO))
RDEFINE STARTED RSED.* DATA('RDZ - RSE DAEMON')
STDATA(USER(STCRSE) GROUP(STCGROUP) TRUSTED(NO))
ALTUSER STCRSE RESTRICTED
To ensure that restricted users do not gain access to z/OS UNIX file system resources through the “other” permission bits, define the RESTRICTED.FILESYS.ACCESS profile in the UNIXPRIV class with UACC(NONE). For more information about restricting user IDs, see Security Server RACF Security Administrator's Guide (SA22-7683).
Attention: If you use restricted
user IDs, explicitly add the permission to access a resource by using
the TSO PERMIT or the z/OS UNIX setfacl commands.
The resources include those resources where the Developer
for System z documentation
uses UACC, such as the ** profile in the PROGRAM class,
or where it relies on common z/OS UNIX conventions, such as everyone
having read and execute permission for Java libraries.
Test the access before activating it on a production system.
|
RSE requires UPDATE access to the BPX.SERVER profile to create or delete the security environment for the client’s thread. If this profile is not defined, UID(0) is required for RSE. This step is required for clients to be able to connect.
Integrated Debugger requires UPDATE access to the BPX.SERVER profile to create or delete the security environment for the debug thread. If this profile is not defined, UID(0) is required for the STCDBM started task user ID. This permit is only required when the optional Integrated Debugger feature is used.
Attention: Defining the BPX.SERVER profile
makes z/OS UNIX as a whole switch from UNIX level security to z/OS UNIX level
security, which is more secure. This switch might impact other z/OS UNIX applications
and operations. Test the security before activating it on a production
system. For more information about the different security levels,
see UNIX System Services
Planning (GA22-7800).
|
Servers with authority to BPX.SERVER must run in a clean, program-controlled environment. This requirement implies that all programs called by RSE must also be program controlled. For MVS load libraries, program control is managed by your security software. This step is required for clients to be able to connect.
The following additional prerequisite libraries must be made program controlled to support the use of optional services. This list does not include data sets that are specific to a product that Developer for System z interacts with, such as IBM File Manager.
The client's password or other means of identification, such as an X.509 certificate is used only to verify the identity upon connection. Afterward, PassTickets are used to maintain thread security. This step is required for clients to be able to connect.
RDEFINE PTKTDATA FEKAPPL UACC(NONE) SSIGNON(KEYMASKED(key16))
APPLDATA('NO REPLAY PROTECTION – DO NOT CHANGE')
DATA('RATIONAL DEVELOPER FOR SYSTEM Z')
RDEFINE PTKTDATA IRRPTAUTH.FEKAPPL.* UACC(NONE)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z')
PERMIT IRRPTAUTH.FEKAPPL.* CLASS(PTKTDATA) ACCESS(UPDATE) ID(STCRSE)
SETROPTS RACLIST(PTKTDATA) REFRESH
RSE supports the using of an application ID other than FEKAPPL. Uncomment and customize the "APPLID=FEKAPPL" option in rsed.envvars to activate this, as documented in "Defining extra Java startup parameters with _RSE_JAVAOPTS" in the IBM Rational Developer for System z Host Configuration Guide. The PTKTDATA class definitions must match the actual application ID used by RSE.
Attention: The client connection
request fails if PassTickets are not set up correctly.
|
The MODIFY LOGS operator command uses the RSED started task user ID to collect host logs and setup information. And by default, user log files are created with secure file access permissions (only owner has access). To be able to collect secure user log files, the RSED started task user ID must be permitted to read them.
The OWNER argument of the MODIFY LOGS operator command results in the specified user ID becoming the owner of the collected data. In order to change ownership, the RSED started task user ID must be permitted to use the CHOWN z/OS UNIX service.
Note that when the SUPERUSER.FILESYS.ACLOVERRIDE profile is defined, access permissions defined in ACL (access Control List) take precedence over the permissions granted through SUPERUSER.FILESYS. The RSED started task user ID will need READ access permit to the SUPERUSER.FILESYS.ACLOVERRIDE profile to bypass ACL definitions.
During client logon, RSE daemon verifies that a user is allowed to use the application.
RDEFINE APPL FEKAPPL UACC(READ) DATA('RATIONAL DEVELOPER FOR SYSTEM Z')
SETROPTS RACLIST(APPL) REFRESH
Servers with authority to BPX.SERVER must run in a clean, program-controlled environment. This requirement implies that all programs called by RSE must also be program controlled. For z/OS UNIX files, program control is managed by the extattr command. To execute this command, you need READ access to BPX.FILEATTR.PROGCTL in the FACILITY class, or be UID(0).
$ ls -Eog /usr/lib/libIRRRacf*.so
-rwxr-xr-x aps- 2 69632 Oct 5 2007 /usr/lib/libIRRRacf.so
-rwxr-xr-x aps- 2 69632 Oct 5 2007 /usr/lib/libIRRRacf64.so
JES Job Monitor issues all JES operator commands requested by a user through an extended MCS (EMCS) console, whose name is controlled with the CONSOLE_NAME directive, as documented in "FEJJCNFG, JES Job Monitor configuration file" in the IBM Rational Developer for System z Host Configuration Guide.
RDEFINE OPERCMDS MVS.MCSOPER.#console UACC(READ)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z')
RDEFINE OPERCMDS JES%.** UACC(NONE)
PERMIT JES%.** CLASS(OPERCMDS) ACCESS(UPDATE) WHEN(CONSOLE(JMON)) ID(*)
SETROPTS RACLIST(OPERCMDS) REFRESH
Attention: Defining JES commands
with universal access NONE in your security software
might impact other applications and operations. Test the security
before activating it on a production system.
|
Table 12 and Table 13 show the operator commands issued for JES2 and JES3, and the discrete security profiles that can be used to protect them.
Action | Command | OPERCMDS profile | Required access |
---|---|---|---|
Hold | $Hx(jobid) with x = {J, S or T} |
|
UPDATE |
Release | $Ax(jobid) with x = {J, S or T} |
|
UPDATE |
Cancel | $Cx(jobid) with x = {J, S or T} |
|
UPDATE |
Purge | $Cx(jobid),P with x = {J, S or T} |
|
UPDATE |
Action | Command | OPERCMDS profile | Required access |
---|---|---|---|
Hold | *F,J=jobid,H |
|
UPDATE |
Release | *F,J=jobid,R |
|
UPDATE |
Cancel | *F,J=jobid,C |
|
UPDATE |
Purge | *F,J=jobid,C |
|
UPDATE |
Assuming the identity of the JES Job Monitor server by creating a JMON console from a TSO session is prevented by your security software. Even though the console can be created, the point of entry is different; for example, JES Job Monitor versus TSO. JES commands issued from this console will fail the security check if your security is set up as documented in this publication and the user does not have authority to the JES commands through other means.
Users require READ access to one of the listed AQE.AUTHDEBUG.* profiles to be able to use the Integrated Debugger for debugging problem-state programs. Users permitted to the AQE.AUTHDEBUG.AUTHPGM profile are also allowed to debug APF authorized programs. Replace the #apf placeholder with valid user IDs or RACF group names for those users that are allowed to debug authorized programs.
RDEFINE FACILITY AQE.AUTHDEBUG.STDPGM UACC(NONE)
PERMIT AQE.AUTHDEBUG.STDPGM CLASS(FACILITY) ACCESS(READ) ID(*)
RDEFINE FACILITY AQE.AUTHDEBUG.AUTHPGM UACC(NONE)
PERMIT AQE.AUTHDEBUG.AUTHPGM CLASS(FACILITY) ACCESS(READ) ID(#apf)
SETROPTS RACLIST(FACILITY) REFRESH
READ access for users and ALTER for system programmers is sufficient for most Developer for System z data sets. Replace the #sysprog placeholder with valid user IDs or RACF group names. Also, ask the system programmer who installed and configured the product for the correct data set names. FEK is the default high-level qualifier used during installation and FEK.#CUST is the default high-level qualifier for data sets created during the customization process.
ADDGROUP (FEK) OWNER(IBMUSER) SUPGROUP(SYS1)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z - HLQ STUB')
ADDSD 'FEK.*.**' UACC(READ)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z')
PERMIT 'FEK.*.**' CLASS(DATASET) ACCESS(ALTER) ID(#sysprog)
SETROPTS GENERIC(DATASET) REFRESH
ADDSD 'FEK.#CUST.LSTRANS.*.**' UACC(UPDATE)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z - SCLMDT')
PERMIT 'FEK.#CUST.LSTRANS.*.**' CLASS(DATASET) ACCESS(ALTER) ID(#sysprog)
SETROPTS GENERIC(DATASET) REFRESH
ADDSD 'FEK.#CUST.CRA*.**' UACC(READ)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z - CARMA')
PERMIT 'FEK.#CUST.CRA*.**' CLASS(DATASET) ACCESS(ALTER) ID(#sysprog)
PERMIT 'FEK.#CUST.CRA*.**' CLASS(DATASET) ACCESS(UPDATE) ID(#ram-developer)
SETROPTS GENERIC(DATASET) REFRESH
ADDSD 'FEK.#CUST.ADNREP*.**' UACC(READ)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z - ADN')
PERMIT 'FEK.#CUST.ADNREP*.**' CLASS(DATASET) ACCESS(ALTER) ID(#sysprog)
PERMIT 'FEK.#CUST.ADNREP*.**' CLASS(DATASET) ACCESS(UPDATE) ID(#cicsadmin)
SETROPTS GENERIC(DATASET) REFRESH
ADDSD 'FEK.#CUST.ADNMAN*.**' UACC(UPDATE)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z - ADN')
PERMIT 'FEK.#CUST.ADNMAN*.**' CLASS(DATASET) ACCESS(ALTER) ID(#sysprog)
SETROPTS GENERIC(DATASET) REFRESH
ADDGROUP (FEK)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z - HLQ STUB')
OWNER(IBMUSER) SUPGROUP(SYS1)"
ADDSD 'FEK.*.**' UACC(NONE)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z')
ADDSD 'FEK.SFEKAUTH' UACC(NONE)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z')
ADDSD 'FEK.SFEKLOAD' UACC(NONE)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z')
ADDSD 'FEK.SFEKLMOD' UACC(NONE)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z')
ADDSD 'FEK.SFEKPROC' UACC(NONE)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z')
ADDSD 'FEK.#CUST.PARMLIB' UACC(NONE)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z')
ADDSD 'FEK.#CUST.CNTL' UACC(NONE)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z')
ADDSD 'FEK.#CUST.SQL' UACC(NONE)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z')
ADDSD 'FEK.#CUST.LSTRANS.*.**' UACC(NONE)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z - SCLMDT')
ADDSD 'FEK.#CUST.CRA*.**' UACC(NONE)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z - CARMA')
ADDSD 'FEK.#CUST.ADNREP*.**' UACC(NONE)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z - ADN')
ADDSD 'FEK.#CUST.ADNMAN*.**' UACC(NONE)
DATA('RATIONAL DEVELOPER FOR SYSTEM Z - ADN')
PERMIT 'FEK.*.** CLASS(DATASET) ACCESS(ALTER) ID(#sysprog)
PERMIT 'FEK.SFEKAUTH CLASS(DATASET) ACCESS(ALTER) ID(#sysprog)
PERMIT 'FEK.SFEKLOAD CLASS(DATASET) ACCESS(ALTER) ID(#sysprog)
PERMIT 'FEK.SFEKLMOD CLASS(DATASET) ACCESS(ALTER) ID(#sysprog)
PERMIT 'FEK.SFEKPROC CLASS(DATASET) ACCESS(ALTER) ID(#sysprog)
PERMIT 'FEK.#CUST.PARMLIB CLASS(DATASET) ACCESS(ALTER) ID(#sysprog)
PERMIT 'FEK.#CUST.CNTL CLASS(DATASET) ACCESS(ALTER) ID(#sysprog)
PERMIT 'FEK.#CUST.SQL CLASS(DATASET) ACCESS(ALTER) ID(#sysprog)
PERMIT 'FEK.#CUST.LSTRANS.*.**' CLASS(DATASET) ACCESS(ALTER) ID(#sysprog)
PERMIT 'FEK.#CUST.CRA*.**' CLASS(DATASET) ACCESS(ALTER) ID(#sysprog)
PERMIT 'FEK.#CUST.ADNREP*.**' CLASS(DATASET) ACCESS(ALTER) ID(#sysprog)
PERMIT 'FEK.#CUST.ADNMAN*.**' CLASS(DATASET) ACCESS(ALTER) ID(#sysprog)
PERMIT 'FEK.SFEKAUTH' CLASS(DATASET) ACCESS(READ) ID(*)
PERMIT 'FEK.SFEKLOAD' CLASS(DATASET) ACCESS(READ) ID(*)
PERMIT 'FEK.SFEKPROC' CLASS(DATASET) ACCESS(READ) ID(*)
PERMIT 'FEK.#CUST.CNTL' CLASS(DATASET) ACCESS(READ) ID(*)
PERMIT 'FEK.#CUST.SQL' CLASS(DATASET) ACCESS(READ) ID(*)
PERMIT 'FEK.SFEKAUTH' CLASS(DATASET) ACCESS(READ) ID(STCJMON)
PERMIT 'FEK.#CUST.PARMLIB' CLASS(DATASET) ACCESS(READ) ID(STCJMON)
PERMIT 'FEK.#CUST.LSTRANS.*.**' CLASS(DATASET) ACCESS(UPDATE) ID(*)
PERMIT 'FEK.#CUST.CRA*.**' CLASS(DATASET) ACCESS(UPDATE) ID(#ram-developer)
PERMIT 'FEK.#CUST.ADNREP*.**' CLASS(DATASET) ACCESS(READ) ID(*)
PERMIT 'FEK.#CUST.ADNREP*.**' CLASS(DATASET) ACCESS(UPDATE) ID(#cicsadmin)
PERMIT 'FEK.#CUST.ADNMAN*.**' CLASS(DATASET) ACCESS(UPDATE) ID(*)
PERMIT 'FEK.SFEKLOAD' CLASS(DATASET) ACCESS(READ) ID(#cicsts)
PERMIT 'FEK.SFEKLMOD' CLASS(DATASET) ACCESS(READ) ID(#cicsts)
PERMIT 'FEK.SFEKLMOD' CLASS(DATASET) ACCESS(READ) ID(#ims)
PERMIT 'FEK.SFEKLMOD' CLASS(DATASET) ACCESS(READ) ID(#batch)
SETROPTS GENERIC(DATASET) REFRESH
Use the following sample commands to display the results of your security-related customizations.
Developer for System z uses TCP/IP to provide mainframe access to users on a non-mainframe workstation. It also uses TCP/IP for communication between various components and other products.
Note that most Developer for System z functions are z/OS UNIX based, and thus TCP/IP will use the z/OS UNIX search order to find its configuration files. See Setting up TCP/IP for more information.
Figure 10 shows the TCP/IP ports that can be used by Developer for System z. The arrows show which party does the bind (arrowhead side) and which one connects.
If you use the PORT or PORTRANGE statement in PROFILE.TCPIP to reserve the ports used by Developer for System z, note that many binds are done by threads active in an RSE thread pool. The job name of the RSE thread pool is RSEDx, where RSED is the name of the RSE started task, and x is a random single digit number, so wildcards are required in the definition.
PORT 4035 TCP RSED ; Developer for System z - RSE daemon
PORT 6715 TCP JMON ; Developer for System z - JES job monitor
PORT 5335 TCP DBGMGR ; Developer for System z – Integrated
debugger
PORT 5336 TCP DBGMGR ; Developer for System z – Integrated
debugger
PORTRange 8108 11 TCP RSED* ; Developer for System z - _RSE_PORTRANGE
;PORTRange 5227 100 TCP RSED* ; Developer for System z - CARMA
CARMA (Common Access Repository Manager) is used to access a host-based Software Configuration Manager (SCM), for example CA Endevor® SCM. In most cases, like for RSE daemon, a server binds to a port and listens for connection requests. CARMA however uses a different approach, as the CARMA server is not active yet when the client initiates the connection request.
When the client sends a connection request, the CARMA miner, which is active as a user thread in an RSE thread pool, will request an ephemeral port or find a free port in the range specified in the CRASRV.properties configuration file and binds to it. The miner then starts the CARMA server and passes the port number, so that the server knows to which port to connect. When the server is connected, the client can send requests to the server and receive the results.
From a TCP/IP perspective, RSE (by way of the CARMA miner) is the server that binds to the port, and the CARMA server is the client connecting to it.
If you use the PORT or PORTRANGE statement in PROFILE.TCPIP to reserve the port range used by CARMA, note that the CARMA miner is active in an RSE thread pool. The jobname of the RSE thread pool is RSEDx, where RSED is the name of the RSE started task and x is a random single digit number, so wildcards are required in the definition.
PORTRange 5227 100 RSED* ; Developer for System z - CARMA
Delayed ACK delays the receipt acknowledgement (ACK) of a TCP packet by up to 200ms. This delay increases the chance that the ACK can be sent along with the response to the received packet, reducing network traffic. However, if the sender is waiting for the ACK before sending a new packet (for example, due to implementation of Nagle’s algorithm), and there is no response to the packet just sent (for example, because it is part of a file transfer), communication is unnecessary delayed.
Developer for System z allows you to disable the delayed ACK function. On the host, this is done with the DSTORE_TCP_NO_DELAY directive in rsed.envvars, as documented in the Host Configuration Guide (SC23-7658).
z/OS Communication Server allows you to have multiple TCP/IP stacks concurrently active on a single system. This is referred to as a CINET setup.
If Developer for System z is not active on the default stack, then selected Developer for System z functions might fail. Using stack affinity is a sure way to resolve this. Stack affinity instructs Developer for System z to use only a specific TCP/IP stack (instead of every available TCP/IP stack, which is the default for the started tasks).
Stack affinity is set for the RSED started task by uncommenting and customizing the _BPXK_SETIBMOPT_TRANSPORT directive in the rsed.envvars configuration file. See the related section in "Chapter 2 Basic Customization" of the Host Configuration Guide (SC23-7658) for more details on customizing this configuration file.
CARMA (Common Access Repository Manager) is used to access a host-based Software Configuration Manager (SCM), for example CA Endevor® SCM. To do so, CARMA starts a user-specific server, which needs additional configuration to enforce stack affinity.
Similar to the Developer for System z started tasks, stack affinity for a CARMA server is set with the _BPXK_SETIBMOPT_TRANSPORT variable, which must be passed on to LE (Language Environment). This can be done by adjusting the startup command in the active crastart*.conf or CRASUB* configuration file.
... PARM(&CRAPRM1. &CRAPRM2.)
... PARM(ENVAR("_BPXK_SETIBMOPT_TRANSPORT=TCPIP") / &CRAPRM1. &CRAPRM2.)
... PARM(&PORT &TIMEOUT)
... PARM(ENVAR("_BPXK_SETIBMOPT_TRANSPORT=TCPIP") / &PORT &TIMEOUT)
Distributed DVIPA (Dynamic Virtual IP Addressing) allows you to concurrently run identical Developer for System z setups on different systems in your sysplex, and have TCP/IP, optionally with the help of WLM, distribute the client connections among these systems.
Therefore, Developer for System z requires the definition of SYSPLEXPORTS in the VIPADISTRIBUTE statement to ensure that the ports used by the RSE server threads are unique within the sysplex.
JES Job Monitor, CARMA, and other Developer for System z servers only interact with the local RSE, and thus do not require a DVIPA setup.
Integrated Debugger interacts with the local RSE, and thus does not require a DVIPA setup. To ensure that debug sessions communicate with the correct host, the debug manager dictates to the client which TCP/IP address must be used, and thus does not require a DVIPA setup.
Distributed DVIPAs are defined by the VIPADEFine and VIPABackup keywords of the VIPADynamic block in your TCP/IP profile. The VIPADISTribute keyword adds the required Sysplex Distributor definitions. Distributed DVIPA requires that all participating stacks are sysplex-aware, which is done via the SYSPLEXRouting and DYNAMICXCF keywords of the IPCONFIG block in your TCP/IP profile. See Communications Server: IP Configuration Reference (SC31-8776) for more details on these directives.
See MVS Setting Up a Sysplex (SA22-7625) and Communication Server: SNA Network Implementation Guide (SC31-8777) for more information about setting up the EZBEPORTS structure in your coupling facility.
The usage of SYSPLEXPORTS implies that TCP/IP will select an ephemeral port for the secondary connection. An ephemeral port is any port that is free and not reserved in any way. The usage of an ephemeral port clashes with firewall best-practice to limit the ports that are opened for communication, because it is unknown which port will be used.
You can bypass this problem by forcing Developer for System z to use known ports for the secondary connection by defining a unique _RSE_PORTRANGE per system, and ensuring that the port ranges used are reserved for Developer for System z usage on all systems. You should note that this bypass requires TCP/IP APAR PM63379.
To ensure that TCP/IP will route the secondary connection to the correct system, Developer for System z must use a unique port range on each system. This implies that you cannot use a shared, identical, setup for the systems as _RSE_PORTRANGE in rsed.envvars must be unique. See Identical software level, different configuration files in Running multiple instances for information about how to set up multiple servers with different configuration files while using the same code. You should use a master copy of rsed.envvars and a script to adjust and copy it to a system-specific setup to ensure the file remains identical across the different systems.
$ oedit /etc/rdz/rsed.envvars
-> add the following at the END:
# -- NEEDED TO FIND THE REMAINING CONFIGURATION FILES
CFG_BASE=/etc/rdz
CLASSPATH=.:$CFG_BASE:$CLASSPATH
# --
$ oedit /etc/rdz/update.sh
$ chmod 755 /etc/rdz/update.sh
#! /bin/sh
# Licensed materials - Property of IBM
# 5724-T07 Copyright IBM Corp. 2012
# clone rsed.envvars and set PORTRANGE for use with RDz & DDVIPA
file=rsed.envvars #; echo file $file
sys=${1:-$(sysvar SYSNAME)} #; echo sys $sys
dir=$(dirname $0) #; echo dir $dir
# if sysname has a special char, precede it with \ (eg. SYS\$1)
case "$sys" in # #### CUSTOMIZE THIS SECTION ####
"SYS1") range=8108-8118;;
"SYS2") range=8119-8129;;
esac #; echo range $range
echo "setting port range $range for $sys using $dir/$file"
if test ! $range ; then
echo ERROR: no port range defined for $sys ; exit 12 ; fi
if test ! -e $dir/$file ; then
echo ERROR: file $dir/$file does not exist ; exit 12 ; fi
if test ! -d $dir/$sys ; then
echo ERROR: directory $dir/$sys does not exist ; exit 12 ; fi
mv $dir/$sys/$file $dir/$sys/prev.$file 2>/dev/null
sed="/_RSE_PORTRANGE/s/.*/_RSE_PORTRANGE=$range/"
sed "$sed" $dir/$file > $dir/$sys/$file
if test ! -s $dir/$sys/$file ; then
echo ERROR creating $dir/$sys/$file, restoring backup
mv $dir/$sys/prev.$file $dir/$sys/$file ; exit 8 ; fi
$ mkdir /etc/rdz/SYS1 /etc/rdz/SYS2
$ /etc/rdz/update.sh SYS1
setting port range 8108-8118 for SYS1 using
/etc/rdz/rsed.envvars
$ /etc/rdz/update.sh SYS2
setting port range 8119-8129 for SYS2 using
/etc/rdz/rsed.envvars
// CNFG='/etc/rdz/&SYSNAME.'
PORTRange 8108 22 RSED* ; 8108-8129 - Developer for System z
; - secondary connection
As documented in Connection flow, the port range in _RSE_PORTRANGE can be small. RSE server does not need the port exclusively for the duration of the client connection. It is only in the time span between the (server) bind and the (client) connect that no other RSE server can bind to the port. This means that most connections will be using the first port in the range, with the rest of the range being a buffer in case of multiple simultaneous logons.
In the following sample setup there are two z/OS systems, SYS1 and SYS2, which are part of a sysplex. System SYS1 is defined as the system that normally hosts the Sysplex Distributor for the Developer for System z distributed DVIPA.
After defining the distributed DVIPA, Developer for System z can be started on the systems to allow load balancing client connections across the systems. JES Job Monitor only interacts with the local RSE, and thus does not require a DVIPA setup. Clients will connect to port 4035 on IP address 10.10.10.1.
IPCONFIG
SYSPLEXRouting
; SYSPLEXROUTING is required as this stack needs sysplex communication
DYNAMICXCF 9.9.9.1 255.255.255.0 1
; DYNAMICXCF defines device/link with home address 9.9.9.1 as needed
IGNORERedirect
VIPADYNAMIC
VIPADEFINE 255.255.255.0 10.10.10.1
; VIPADEFINE defines 10.10.10.1 as main DVIPA on SYS1 for RDz
VIPADISTRIBUTE DEFINE
; VIPADISTRIBUTE makes 10.10.10.1 a distributed DVIPA, must match SYS2
SYSPLEXPORTS ; RDz prereq
DISTMETHOD BASEWLM ; BASEWLM or ROUNDROBIN
10.10.10.1 ; DVIPA address used by RDz clients
PORT 4035 ; port used by RDz clients
DESTIP 9.9.9.1 9.9.9.2 ; RDz active on SYS1 and SYS2
ENDVIPADYNAMIC
IPCONFIG
SYSPLEXRouting
; SYSPLEXROUTING is required as this stack needs sysplex communication
DYNAMICXCF 9.9.9.2 255.255.255.0 1
; DYNAMICXCF defines device/link with home address 9.9.9.2 as needed
IGNORERedirect
VIPADYNAMIC
VIPABACKUP 255.255.255.0 10.10.10.1
; VIPABACKUP defines 10.10.10.1 as backup DVIPA on SYS2 for RDz
VIPADISTRIBUTE DEFINE
; VIPADISTRIBUTE makes 10.10.10.1 a distributed DVIPA, must match SYS1
SYSPLEXPORTS ; RDz prereq
DISTMETHOD BASEWLM ; BASEWLM or ROUNDROBIN
10.10.10.1 ; DVIPA address used by RDz clients
PORT 4035 ; port used by RDz clients
DESTIP 9.9.9.1 9.9.9.2 ; RDz active on SYS1 and SYS2
ENDVIPADYNAMIC
Unlike traditional z/OS applications, Developer for System z is not a monolithic application that can be identified easily to Workload Manager (WLM). Developer for System z consists of several components that interact to give the client access to the host services and data. As described in Understanding Developer for System z, some of these services are active in different address spaces, resulting in different WLM classifications.
Figure 13 shows a basic overview of the subsystems through which Developer for System z workloads are presented to WLM.
Application Deployment Manager (ADM) is active within a CICS region, and will therefore follow the CICS classification rules in WLM.
RSE daemon (RSED), Debug Manager (DBGMGR) and JES Job Monitor (JMON) are Developer for System z started tasks (or long-running batch jobs), each with their individual address space.
As documented in RSE as a Java application, RSE daemon spawns a child process for each RSE thread pool server (which supports a variable number of clients). Each thread pool is active in a separate address space (using a z/OS UNIX initiator, BPXAS). Because these are spawned processes, they are classified using the WLM OMVS classification rules, not the started task classification rules.
The clients that are active in a thread pool can create a multitude of other address spaces, depending on the actions done by the users. Depending on the configuration of Developer for System z, some workloads, such as the TSO Commands service (TSO cmd) or CARMA, can run in different subsystems.
The address spaces listed in Figure 13 remain in the system long enough to be visible, but you should be aware that due to the way z/OS UNIX is designed, there are also several short-lived temporary address spaces. These temporary address spaces are active in the OMVS subsystem.
Note that while the RSE thread pools use the same user ID and a similar job name as the RSE daemon, all address spaces started by a thread pool are owned by the user ID of the client requesting the action. The client user ID is also used as (part of) the job name for all OMVS-based address spaces stated by the thread pool.
More address spaces are created by other services that Developer for System z uses, such as File Manager (FMNCAS) or z/OS UNIX REXEC (USS build).
WLM uses classification rules to map work coming into the system to a service class. This classification is based upon work qualifiers. The first (mandatory) qualifier is the subsystem type that receives the work request. Table 14 lists the subsystem types that can receive Developer for System z workloads.
Subsystem type | Work description |
---|---|
ASCH | The work requests include all APPC transaction programs scheduled by the IBM-supplied APPC/MVS transaction scheduler, ASCH. |
CICS | The work requests include all transactions processed by CICS. |
JES | The work requests include all jobs that JES2 or JES3 initiates. |
OMVS | The work requests include work processed in z/OS UNIX System Services forked children address spaces. |
STC | The work requests include all work initiated by the START and MOUNT commands. STC also includes system component address spaces. |
Table 15 lists additional qualifiers that can be used to assign a workload to a specific service class. Refer to MVS Planning: Workload Management (SA22-7602) for more details on the listed work qualifiers.
ASCH | CICS | JES | OMVS | STC | ||
---|---|---|---|---|---|---|
AI | Accounting Information | x | x | x | x | |
LU | LU Name (*) | x | ||||
PF | Perform (*) | x | x | |||
PRI | Priority | x | ||||
SE | Scheduling Environment Name | x | ||||
SSC | Subsystem Collection Name | x | ||||
SI | Subsystem Instance (*) | x | x | |||
SPM | Subsystem Parameter | x | ||||
PX | Sysplex Name | x | x | x | x | x |
SY | System Name (*) | x | x | x | ||
TC | Transaction/Job Class (*) | x | x | |||
TN | Transaction/Job Name (*) | x | x | x | x | x |
UI | User ID (*) | x | x | x | x | x |
As documented in Workload classification, Developer for System z creates different types of workloads on your system. These different tasks communicate with each other, which implies that the actual elapse time becomes important to avoid time-out issues for the connections between the tasks. As a result, Developer for System z tasks should be placed in high-performance service classes, or in moderate-performance service classes with a high priority.
A revision, and possibly an update, of your current WLM goals is therefore advised. This is especially true for traditional MVS shops new to time-critical OMVS workloads.
Table 16 lists the address spaces that are used by Developer for System z. z/OS UNIX will substitute "x" in the "Task Name" column by a random 1-digit number.
Description | Task name | Workload |
---|---|---|
Debug Manager | DBGMGR | STC |
JES Job Monitor | JMON | STC |
RSE daemon | RSED | STC |
RSE thread pool | RSEDx | OMVS |
ISPF Client Gateway (TSO Commands service and SCLMDT) | <userid>x | OMVS |
TSO Commands service (APPC) | FEKFRSRV | ASCH |
CARMA (batch) | CRA<port> | JES |
CARMA (crastart) | <userid>x | OMVS |
CARMA (ISPF Client Gateway) | <userid> and <userid>x | OMVS |
MVS build (batch job) | * | JES |
z/OS UNIX build (shell commands) | <userid>x | OMVS |
z/OS UNIX shell | <userid> | OMVS |
Application Deployment Manager | CICSTS | CICS |
All Developer for System z started tasks, RSE daemon and JES Job Monitor, are servicing real-time client requests.
Description | Task name | Workload |
---|---|---|
JES Job Monitor | JMON | STC |
Debug Manager | DBGMGR | STC |
RSE daemon | RSED | STC |
JES Job Monitor provides all JES-related services such as submitting jobs, browsing spool files and executing JES operator commands. You should specify a high-performance, one-period velocity goal, because the task does not report individual transactions to WLM. Resource usage depends heavily on user actions, and will therefore fluctuate, but is expected to be minimal to moderate.
Debug Manager provides services to connect programs being debugged to clients debugging them. You should specify a high-performance, one-period velocity goal, because the task does not report individual transactions to WLM. Resource usage depends heavily on user actions, and will therefore fluctuate, but is expected to be minimal.
RSE daemon handles client logon and authentication, and manages the different RSE thread pools. You should specify a high-performance, one-period velocity goal, because the task does not report individual transactions to WLM. Resource usage is expected to be moderate, with a peak at the beginning of the workday.
The OMVS workloads can be divided into two groups, RSE thread pools and everything else. This because all workloads, except RSE thread pools, use the client user ID as base for the address space name. (z/OS UNIX will substitute "x" in the "Task Name" column by a random 1-digit number.)
Description | Task name | Workload |
---|---|---|
RSE thread pool | RSEDx | OMVS |
ISPF Client Gateway (TSO Commands service and SCLMDT) | <userid>x | OMVS |
CARMA (crastart) | <userid>x | OMVS |
CARMA (ISPF Client Gateway) | <userid> and <userid>x | OMVS |
z/OS UNIX build (shell commands) | <userid>x | OMVS |
z/OS UNIX shell | <userid> | OMVS |
An RSE thread pool is like the heart and brain of Developer for System z. Almost all data flows through here, and the miners (user specific threads) inside the thread pool control the actions of most other Developer for System z related tasks. You should specify a high-performance, one-period velocity goal, because the task does not report individual transactions to WLM. Resource usage depends heavily on user actions, and will therefore fluctuate, but is expected to be substantial.
The remaining workloads will all end up in the same service class due to a common address space naming convention. You should specify a multi-period goal for this service class. The first periods should be high-performance, percentile response time goals, while the last period should have a moderate-performance velocity goal. Some workloads, such as the ISPF Client Gateway, will report individual transactions to WLM, while others do not.
The ISPF Client Gateway is an ISPF service invoked by Developer for System z to execute non-interactive TSO and ISPF commands. This includes explicit commands issued by the client as well as implicit commands issued by Developer for System z, such as getting a PDS member list. Resource usage depends heavily on user actions, and will therefore fluctuate, but is expected to be minimal.
CARMA is an optional Developer for System z server that is used to interact with host based Software Configuration Managers (SCMs), such as CA Endevor® SCM. Developer for System z allows for different startup methods for a CARMA server, some of which become an OMVS workload. Resource usage depends heavily on user actions, and will therefore fluctuate, but is expected to be minimal.
When a client initiates a build for a z/OS UNIX project, z/OS UNIX REXEC (or SSH) will start a task that executes a number of z/OS UNIX shell commands to perform the build. Resource usage depends heavily on user actions, and will therefore fluctuate, but is expected to be moderate to substantial, depending on the size of the project.
This workload processes z/OS UNIX shell commands that are issued by the client. Resource usage depends heavily on user actions, and will therefore fluctuate, but is expected to be minimal.
JES-managed batch processes are used in various manners by Developer for System z. The most common usage is for MVS builds, where a job is submitted and monitored to determine when it ends. But Developer for System z could also start a CARMA server in batch, and communicate with it using TCP/IP.
Description | Task name | Workload |
---|---|---|
CARMA (batch) | CRA<port> | JES |
MVS build (batch job) | * | JES |
CARMA is an optional Developer for System z server that is used to interact with host based Software Configuration Managers (SCMs), such as CA Endevor® SCM. Developer for System z allows for different startup methods for a CARMA server, some of which become a JES workload. You should specify a high-performance, one-period velocity goal, because the task does not report individual transactions to WLM. Resource usage depends heavily on user actions, and will therefore fluctuate, but is expected to be minimal.
In the current Developer for System z versions, the ISPF Client Gateway is used to execute non-interactive TSO and ISPF commands. Due to historical reasons, Developer for System z also supports executing these commands via an APPC transaction. You should note that the APPC method is deprecated.
Description | Task name | Workload |
---|---|---|
TSO Commands service (APPC) | FEKFRSRV | ASCH |
The TSO Commands service can be started as an APPC transaction by Developer for System z to execute non-interactive TSO and ISPF commands. This includes explicit commands issued by the client as well as implicit commands issued by Developer for System z, such as getting a PDS member list. You should specify a multi-period goal for this service class. For the first periods, you should specify high-performance, percentile response time goals. For the last period, you should specify a moderate-performance velocity goal. Resource usage depends heavily on user actions, and will therefore fluctuate, but is expected to be minimal.
Application Deployment Manager is an optional Developer for System z server that is active inside a CICS Transaction Server region.
Description | Task name | Workload |
---|---|---|
Application Deployment Manager | CICSTS | CICS |
The optional Application Deployment Manager server, which is active inside a CICSTS region, allows you to securely offload selected CICSTS management tasks to developers. Resource usage depends heavily on user actions, and will therefore fluctuate, but is expected to be minimal. The type of service class you should use depends on the other transactions active in this CICS region, and is therefore not discussed in detail.
The goal is set to a service class that manages the CICS address spaces. You can only use an execution velocity goal for this service class. WLM uses the JES or STC classification rules for the address spaces but does not use the CICS subsystem classification rules for transactions.
A response time goal can be set in a service class assigned to a single transaction or a group of transactions. WLM uses the JES or STC classification rules for the address spaces and the CICS subsystem classification rules for transactions.
As explained in Understanding Developer for System z, RSE (Remote Systems Explorer) is the core of Developer for System z. To manage the connections and workloads from the clients, RSE is composed of a daemon address space, which controls thread pooling address spaces. The daemon acts as a focal point for connection and management purposes, while the thread pools process the client workloads.
This makes RSE a prime target for tuning the Developer for System z setup. However, maintaining hundreds of users, each using 17 or more threads, a certain amount of storage, and possibly 1 or more address spaces requires proper configuration of both Developer for System z and z/OS.
Use the information in this section to estimate the normal and maximum resource usage by Developer for System z, so you can plan your system configuration accordingly.
When you use the numbers and formulas presented in this section to define the values for system limits, be aware that you are working with fairly accurate estimates. Leave enough margin when setting the system limits to allow resource usage by temporary and other tasks, or by users connecting multiple times to the host simultaneously. (For example, by way of RSE and TN3270).
Started task | Address spaces | Processes | Threads |
---|---|---|---|
JMON | 1 | 1 | 3 |
DBGMGR | 1 | 1 | 4 |
RSED | 1 | 3 | 16 |
RSEDx | (a) 1 + 2 | 1 + 3 | 1 + 14 |
Requisite software | Address spaces | Processes | Threads |
---|---|---|---|
ISPF Client Gateway | 1 | 2 | 4 |
APPC | 1 | 1 | 2 |
User action | Address spaces User ID |
Processes User ID |
Threads |
||
---|---|---|---|---|---|
Logon | - | - | - | 17 | 1 |
Timer for idle timeout | - | - | - | 1 | - |
Search | - | - | - | 1 | - |
Expand PDS(E) | ISPF | ISPF | ISPF | - | - |
Open data set | ISPF | ISPF | ISPF | 1 | - |
TSO command | ISPF | ISPF | ISPF | - | - |
z/OS UNIX shell | 1 | 1 | 1 | 6 | - |
MVS build | 1 | - | - | - | - |
z/OS UNIX build | 3 | 3 | 3 | - | - |
CARMA (batch) | 1 | 1 | 2 | 1 | - |
CARMA (crastart) | 1 | 1 | 2 | 1 | - |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
CARMA (ispf) | 4 | 4 | 7 | 5 | - |
SCLMDT | ISPF | ISPF | ISPF | - | - |
Count | Description | Task name | Shared | Ends after |
---|---|---|---|---|
1 | JES Job Monitor | JMON | Yes | Never |
1 | Debug Manager | DBGMGR | Yes | Never |
1 | RSE daemon | RSED | Yes | Never |
1 | RSE daemon APF authorized | RSEDx | Yes | Never |
(a) | RSE thread pool | RSEDx | Yes | Never |
(a) | RSE thread pool APF authorized | RSEDx | Yes | Never |
lu | ISPF Client Gateway (TSO Commands service and SCLMDT) | <userid>x | No | 15 minutes or user logoff |
lu | TSO Commands service (APPC) | FEKFRSRV | No | 60 minutes or user logoff |
lu | CARMA (batch) | CRA<port> | No | 7 minutes or user logoff |
lu | CARMA (crastart) | <userid>x | No | 7 minutes or user logoff |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
4u | CARMA (ispf, deprecated) | (1)<userid> or (3)<userid>x | No | 7 minutes or user logoff |
(b) | Simultaneous ISPF Client Gateway usage by 1 user | <userid>x | No | Task completion |
1u | MVS build (batch job) | * | No | Task completion |
3u | z/OS UNIX build (shell commands) | <userid>x | No | Task completion |
1u | z/OS UNIX shell | <userid> | No | User logoff |
X | SCLMDT | TSO by way of Client Gateway | TSO by way of APPC |
---|---|---|---|
1 | No | No | Yes |
1 | No | Yes | No |
1 | Yes | Yes | No |
Y | |
---|---|
0 | No CARMA |
1 | CARMA (batch) |
1 | CARMA (crastart) |
![]() ![]() |
![]() ![]() |
4 | CARMA (ispf, deprecated) |
Location | Limit | Affected resources |
---|---|---|
rsed.envvars | maximum.threadpool.process | Limits the number of RSE thread pools |
IEASYMxx | MAXUSER | Limits the number of address spaces |
ASCHPMxx | MAX | Limits the number of APPC initiators for TSO Commands service (APPC) |
Processes | Address spaces | Description | User ID |
---|---|---|---|
1 | 1 | JES Job Monitor | STCJMON |
1 | 1 | Debug Manager | STCDBM |
3 | 1 | RSE daemon | STCRSE |
1 | 1 | RSE daemon APF-authorized | STCRSE |
2 | (a) | RSE thread pool | STCRSE |
1 | (a) | RSE thread pool APF-authorized | STCRSE |
2 | (b) | ISPF Client Gateway (TSO Commands service and SCLMDT) | <userid> |
2 | (a) | RSE thread pool | STCRSE |
1 | 1u | TSO Commands service (APPC) | <userid> |
1 | 1u | CARMA (batch) | <userid> |
1 | 1u | CARMA (crastart) | <userid> |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
1 | 1u | CARMA (ispf, deprecated) | <userid> |
1 | 3u | z/OS UNIX build (shell commands) | <userid> |
1 | 1u | z/OS UNIX shell | <userid> |
(5) | (u) | SCLM Developer Toolkit | <userid> |
X | SCLMDT | TSO by way of Client Gateway | TSO by way of APPC |
---|---|---|---|
1 | No | No | Yes |
2 | No | Yes | No |
7 | Yes | Yes | No |
Y | |
---|---|
0 | No CARMA |
1 | CARMA (batch) |
1 | CARMA (crastart) |
![]() ![]() |
![]() ![]() |
4 | CARMA (ispf, deprecated) |
Location | Limit | Affected resources |
---|---|---|
BPXPRMxx | MAXPROCSYS | Limits the total number of processes |
BPXPRMxx | MAXPROCUSER | Limits the number of processes per z/OS UNIX UID |
OMVS segment | PROCUSERMAX | Limits the number of processes for a user ID |
Threads |
User ID | Description | ||
---|---|---|---|---|
RSEDx | Active | Bootstrap | ||
- | (f) 3 + 1u | - | STCJMON | JES Job Monitor |
- | 4 | - | STCDBM | Debug Manager |
- | 14 | 2 | STCRSE | RSE daemon |
- | 1 | - | STCRSE | RSE daemon APF authorized |
(a,g) 12 + 8u | - | (a) 1 | STCRSE | RSE thread pool with single-threaded miners |
(a,g) 12 + 19u | - | (a) 1 | STCRSE | RSE thread pool, with multi-threaded miners |
- | (a) 1 | - | STCRSE | RSE thread pool APF authorized |
- | (b) 4u | (b) 1u | <userid> | ISPF Client Gateway (TSO Commands service and SCLMDT) |
- | 2u | - | <userid> | TSO Commands service (APPC) |
1u | 2u | - | STCRSE and <userid> | CARMA (batch) |
![]() ![]() |
2u | - | STCRSE and <userid> | CARMA (crastart) |
![]() ![]() ![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
5u | 4u | 3u | STCRSE and <userid> | CARMA (ispf, deprecated) |
- | (c) 1u | 2u | <userid> | z/OS UNIX build (shell commands) |
6u | 1u | - | STCRSE and <userid> | z/OS UNIX shell |
(d) 1 | - | - | STCRSE | Download |
(e) 1 | - | - | STCRSE | Search |
- | (5) | - | <userid> | SCLM Developer Toolkit |
1u | - | - | STCRSE | Timer for idle timeout |
X | SCLMDT | TSO by way of Client Gateway | TSO by way of APPC | Timeout |
---|---|---|---|---|
0 | No | No | Yes | No |
0 | No | Yes | No | No |
0 | Yes | Yes | No | No |
1 | No | No | Yes | Yes |
1 | No | Yes | No | Yes |
1 | Yes | Yes | No | Yes |
Y | |
---|---|
0 | No CARMA |
1 | CARMA (batch) |
![]() ![]() |
CARMA (crastart) |
![]() ![]() ![]() ![]() |
![]() ![]() |
5 | CARMA (ispf, deprecated) |
Location | Limit | Affected resources |
---|---|---|
OMVS segment | THREADSMAX | Limits the number of threads for a user ID |
BPXPRMxx | MAXTHREADS | Limits the number of threads in a process. |
BPXPRMxx | MAXTHREADTASKS | Limits the number of MVS tasks in a process. |
BPXPRMxx | MAXASSIZE | Limits the address space size, and thus the storage available for thread-related control blocks. |
rsed.envvars | Xmx | Sets the maximum Java heap size. This storage is reserved and thus no longer available for thread-related control blocks. |
rsed.envvars | maximum.clients | Limits the number of clients (and thus their threads) in an RSE thread pool. |
rsed.envvars | maximum.threads | Limits the number of client threads in an RSE thread pool. |
FEJJCNFG | MAX_THREADS | Limits the number of threads in JES Job Monitor. |
The resource usage documented in the previous sections is permanent for the life span of Developer for System z, or semi-permanent for certain user-specific tasks.
Threads |
User ID | Description | ||
---|---|---|---|---|
RSEDx | Active | Bootstrap | ||
- | (f) 3 + 1u | - | STCJMON | JES Job Monitor |
- | 4 | - | STCDBM | Debug Manager |
- | 14 | 2 | STCRSE | RSE daemon |
- | 1 | - | STCRSE | RSE daemon APF authorized |
(a,g) 12 + 8u | - | (a) 1 | STCRSE | RSE thread pool with single-threaded miners |
(a,g) 12 + 19u | - | (a) 1 | STCRSE | RSE thread pool, with multi-threaded miners |
- | (a) 1 | - | STCRSE | RSE thread pool APF authorized |
- | (b) 4u | (b) 1u | <userid> | ISPF Client Gateway (TSO Commands service and SCLMDT) |
- | 2u | - | <userid> | TSO Commands service (APPC) |
1u | 2u | - | STCRSE and <userid> | CARMA (batch) |
![]() ![]() |
2u | - | STCRSE and <userid> | CARMA (crastart) |
![]() ![]() ![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
![]() ![]() |
5u | 4u | 3u | STCRSE and <userid> | CARMA (ispf, deprecated) |
- | (c) 1u | 2u | <userid> | z/OS UNIX build (shell commands) |
6u | 1u | - | STCRSE and <userid> | z/OS UNIX shell |
(d) 1 | - | - | STCRSE | Download |
(e) 1 | - | - | STCRSE | Search |
- | (5) | - | <userid> | SCLM Developer Toolkit |
1u | - | - | STCRSE | Timer for idle timeout |
X | SCLMDT | TSO by way of Client Gateway | TSO by way of APPC | Timeout |
---|---|---|---|---|
0 | No | No | Yes | No |
0 | No | Yes | No | No |
0 | Yes | Yes | No | No |
1 | No | No | Yes | Yes |
1 | No | Yes | No | Yes |
1 | Yes | Yes | No | Yes |
Y | |
---|---|
0 | No CARMA |
1 | CARMA (batch) |
![]() ![]() |
CARMA (crastart) |
![]() ![]() ![]() ![]() |
![]() ![]() |
5 | CARMA (ispf, deprecated) |
Location | Limit | Affected resources |
---|---|---|
OMVS segment | THREADSMAX | Limits the number of threads for a user ID |
BPXPRMxx | MAXTHREADS | Limits the number of threads in a process. |
BPXPRMxx | MAXTHREADTASKS | Limits the number of MVS tasks in a process. |
BPXPRMxx | MAXASSIZE | Limits the address space size, and thus the storage available for thread-related control blocks. |
rsed.envvars | Xmx | Sets the maximum Java heap size. This storage is reserved and thus no longer available for thread-related control blocks. |
rsed.envvars | maximum.clients | Limits the number of clients (and thus their threads) in an RSE thread pool. |
rsed.envvars | maximum.threads | Limits the number of client threads in an RSE thread pool. |
FEJJCNFG | MAX_THREADS | Limits the number of threads in JES Job Monitor. |
RSE is a Java application, which implies that storage (memory) usage planning for Developer for System z must take two storage allocation limits into consideration, Java heap size and Address Space size.
Java offers many services to ease coding efforts for Java applications. One of these services is storage management.
Java’s storage management allocates large blocks of storage and uses these for storage requests by the application. This storage managed by Java is called the Java heap. Periodic garbage collection (defragmentation) reclaims unused space in the heap and reduces its size. Note that, to save CPU cycles, garbage collection tends to wait until the occupied storage is actually needed, thus leaving storage which is no longer used allocated (and becoming paged out) for a longer time than absolutely required.
The maximum Java heap size is defined in rsed.envvars with the Xmx directive. If this directive is not specified, Java uses a default size of 512 MB. You should specify a value of 256 MB or higher. When running in 64-bit mode, Java will attempt to allocate the heap above the 2 GB bar, freeing up space below the bar.
Each RSE thread pool (which services the client actions) is a separate Java application, and thus has a personal Java heap. Note that all thread pools use the same rsed.envvars configuration file, and thus have the same Java heap size limit.
The thread pool’s usage of the Java heap depends heavily on the actions done by the connected clients. Regular monitoring of the heap usage is required to set the optimal heap size limit. Use the modify display process operator command to monitor the Java heap usage by RSE thread pools.
All z/OS applications, including Java applications, are active within an address space, and are thus bound by address space size limitations.
RSE thread pools inherit the address space size limits from RSE daemon. The address space size must be sufficient to house the Java heap, Java itself, common storage areas, and all control blocks the system creates to support the thread pool activity, such as a TCB (Task Control Block) per thread. Note that some of this storage usage is below the 16 MB line. When running in 64-bit mode, Java will attempt to allocate the heap above the 2GB bar, freeing up space below the bar.
You should monitor the actual address space size before changing any settings that influence it, like changing the size of the Java heap or the amount of users supported by a single thread pool. Use your regular system monitoring software to track the actual storage usage by Developer for system z. If you do not have a dedicated monitoring tool, then basic information can be gathered with tools like the SDSF DA view or TASID (an as-is system information tool available via the ISPF "Support and downloads" webpage).
Note that RSE displays the current Java heap and address space size limit during startup in console message FEK004I.
As reference, Table 33 shows values used by actual Developer for System z customers for key rsed.envvars settings that impact storage usage.
xmx (maximum java heap) | maximum.clients | Primary type of development |
---|---|---|
512M | 30 | PL/I |
512M | 10 | COBOL |
384M | 12 | COBOL |
800M (64-bit) | 20 | Not specified |
Max Heap Size=10MB and private AS Size=1,959MB
startup
BPXM023I (STCRSE)
ProcessId(268 ) Memory Usage(7%) Clients(0)
Jobname Cpu time Storage EXCP
-------- ----------- ------- ----------
JMON 0.01 2740 72
RSED 4.47 32.8M 15910
RSED8 1.15 27.4M 12612
logon 1
BPXM023I (STCRSE)
ProcessId(268 ) Memory Usage(13%) Clients(1)
Jobname Cpu time Storage EXCP
-------- ----------- ------- ----------
JMON 0.01 2864 81
RSED 4.55 32.8M 15980
RSED8 3.72 55.9M 24128
logon 2
BPXM023I (STCRSE)
ProcessId(268 ) Memory Usage(23%) Clients(2)
Jobname Cpu time Storage EXCP
-------- ----------- ------- ----------
JMON 0.02 2944 86
RSED 4.58 32.9M 16027
RSED8 4.20 57.8M 25205
logon 3
BPXM023I (STCRSE)
ProcessId(268 ) Memory Usage(37%) Clients(3)
Jobname Cpu time Storage EXCP
-------- ----------- ------- ----------
JMON 0.02 3020 91
RSED 4.60 32.9M 16076
RSED8 4.51 59.6M 26327
logon 4
BPXM023I (STCRSE)
ProcessId(268 ) Memory Usage(41%) Clients(4)
Jobname Cpu time Storage EXCP
-------- ----------- ------- ----------
JMON 0.02 3108 96
RSED 4.61 32.9M 16125
RSED8 4.77 62.3M 27404
logon 5
BPXM023I (STCRSE)
ProcessId(268 ) Memory Usage(41%) Clients(4)
ProcessId(33554706) Memory Usage(13%) Clients(1)
Jobname Cpu time Storage EXCP
-------- ----------- ------- ----------
JMON 0.03 3184 101
RSED 4.64 32.9M 16229
RSED8 4.78 62.4M 27413
RSED9 4.60 56.6M 24065
Max Heap Size=10MB and private AS Size=1,959MB
startup
BPXM023I (STCRSE)
ProcessId(212 ) Memory Usage(7%) Clients(0)
Jobname Cpu time Storage EXCP
-------- ----------- ------- ----------
JMON 0.01 2736 71
RSED 4.35 32.9M 15117
RSED8 1.43 27.4M 12609
logon
BPXM023I (STCRSE)
ProcessId(212 ) Memory Usage(13%) Clients(1)
Jobname Cpu time Storage EXCP
-------- ----------- ------- ----------
JMON 0.01 2864 80
RSED 4.48 33.0M 15187
RSED8 3.53 53.9M 24125
expand large MVS tree (195 data sets)
BPXM023I (STCRSE)
ProcessId(212 ) Memory Usage(13%) Clients(1)
Jobname Cpu time Storage EXCP
-------- ----------- ------- ----------
JMON 0.01 2864 80
RSED 4.58 33.1M 16094
RSED8 4.28 56.1M 24740
expand small PDS (21 members)
BPXM023I (STCRSE)
ProcessId(212 ) Memory Usage(13%) Clients(1)
Jobname Cpu time Storage EXCP
-------- ----------- ------- ----------
IBMUSER2 0.22 2644 870
JMON 0.01 2864 80
RSED 4.61 33.1M 16108
RSED8 4.40 56.2M 24937
open medium sized member (86 lines)
BPXM023I (STCRSE)
ProcessId(212 ) Memory Usage(13%) Clients(1)
Jobname Cpu time Storage EXCP
-------- ----------- ------- ----------
IBMUSER2 0.22 2644 870
JMON 0.01 2864 80
RSED 4.61 33.1M 16108
RSED8 8.12 62.7M 27044
Most of the Developer for System z related data that is not written to a DD statement ends up in a z/OS UNIX file. The system programmer has control over which data is written and where it goes. However, there is no control over the amount of data written.
By default, only error and warning messages are written to the logs. So if all goes as planned, these directories should hold only empty or nearly-empty files (not counting audit logs).
You can enable logging of informational messages, preferably under direction of the IBM support center, which increases the size of log files noticeably.
startup
$ ls -l /var/rdz/logs/server
total 144
-rw-rw-rw- 1 STCRSE STCGRP 33642 Jul 10 12:10 rsedaemon.log
-rw-rw-rw- 1 STCRSE STCGRP 1442 Jul 10 12:10 rseserver.log
logon
$ ls -l /var/rdz/logs/server
total 144
-rw------- 1 STCRSE STCGRP 36655 Jul 10 12:11 rsedaemon.log
-rw------- 1 STCRSE STCGRP 1893 Jul 10 12:11 rseserver.log
$ ls -l /var/rdz/logs/IBMUSER
total 160
-rw------- 1 IBMUSER SYS1 3459 Jul 10 12:11 ffs.log
-rw------- 1 IBMUSER SYS1 0 Jul 10 12:11 ffsget.log
-rw------- 1 IBMUSER SYS1 0 Jul 10 12:11 ffsput.log
-rw------- 1 IBMUSER SYS1 303 Jul 10 12:11 ffslock.log
-rw------- 1 IBMUSER SYS1 7266 Jul 10 12:11 rsecomm.log
logoff
$ ls -l /var/rdz/logs/server
total 80
-rw------- 1 STCRSE STCGRP 36655 Jul 10 12:11 rsedaemon.log
-rw------- 1 STCRSE STCGRP 2208 Jul 10 12:11 rseserver.log
$ ls -l /var/rdz/logs/IBMUSER
total 296
-rw------- 1 IBMUSER SYS1 6393 Jul 10 12:11 ffs.log
-rw------- 1 IBMUSER SYS1 0 Jul 10 12:11 ffsget.log
-rw------- 1 IBMUSER SYS1 0 Jul 10 12:11 ffsput.log
-rw------- 1 IBMUSER SYS1 609 Jul 10 12:11 ffslock.log
-rw------- 1 IBMUSER SYS1 45157 Jul 10 12:11 rsecomm.log
stop
$ ls -l /var/rdz/logs/server
total 80
-rw------- 1 STCRSE STCGRP 36655 Jul 10 12:11 rsedaemon.log
-rw------- 1 STCRSE STCGRP 2490 Jul 10 12:12 rseserver.log
Except for audit logs, log files are overwritten on every restart (for the RSE started task) or logon (for a client), keeping the total size in check. Audit logs are removed after the interval specified in audit.retention.period expires. The keep.last.log directive in rsed.envvars changes this slightly, as it can instruct RSE to keep a copy of the previous logs. Older copies are always removed. If the keep.all.logs directive in rsed.envvars is enabled, all logs have a timestamp appended to their name and the files are removed after the interval specified in log.retention.period expires.
A warning message is sent to the console when the file system holding the log files is running low on free space. This console message (FEK103E) is repeated regularly until the low space issue is resolved. When the file system runs out of space, RSE will attempt to delete existing log files to free up space. Audit logs are not touched by this process.
Location | Directive | Function |
---|---|---|
resecomm.properties | debug_level | Set the default log detail level. |
rsecomm.properties | USER | Enable debug_level 2 for specified users. |
rsed.envvars | keep.all.logs | Keep a copy of the previous logs before startup/logon. |
rsed.envvars | keep.last.log | Keep a copy of the previous logs before startup/logon. |
rsed.envvars | enable.audit.log | Keep an audit trace of client actions. |
rsed.envvars | enable.standard.log | Write the stdout and stderr streams of the thread pool (or pools) to a log file. |
rsed.envvars | DSTORE_TRACING_ON | Enable DataStore action logging. |
rsed.envvars | DSTORE_MEMLOGGING_ON | Enable DataStore memory usage logging. |
Operator command | modify rsecommlog <level> | Dynamically change the log detail level of rsecomm.log |
Operator command | modify rsedaemonlog <level> | Dynamically change the log detail level of rsedaemon.log |
Operator command | modify rseserverlog <level> | Dynamically change the log detail level of rseserver.log |
Operator command | modify rsestandardlog {on|off} | Dynamically change the updating of std*.*.log |
Operator command | modify trace {on|off} USER=userid | Enable debug_level 2 for specified users. |
Operator command | modify trace {on|off} SERVER=pid | Enable debug_level 2 for specified users. |
Operator command | modify trace clear | Disable trace setup. |
Operator command | modify logs | Collect host logs and setup information |
rsed.envvars | daemon.log | Home path for RSE started task and audit logs. |
rsed.envvars | user.log | Home path for user logs. |
rsed.envvars | CGI_ISPWORK | Home path for ISPF Client Gateway logs |
rsed.envvars | TMPDIR | Directory for IVP logs and modify logs operator command |
rsed.envvars | _CEE_DMPTARG | Directory for Java dumps |
Developer for System z, together with requisite software such as the ISPF Client Gateway, also writes temporary data to /tmp and /var/rdz/WORKAREA. The amount of data written here as a result of user actions is unpredictable, so you should have ample free space in the file systems holding these directories.
Developer for System z always tries to clean up these temporary files, but manual cleanup, as documented in "(Optional) WORKAREA and /tmp cleanup" in the Host Configuration Guide (SC23-7658), can be performed at virtually any time.
Location | Directive | Function |
---|---|---|
rsed.envvars | CGI_ISPWORK | Home path for temporary data. |
rsed.envvars | TMPDIR | Directory for temporary data. |
The environment variables defined in rsed.envvars are used by RSE, Java, and z/OS UNIX. The sample file that comes with Developer for System z is targeted at small to medium sized installations that do not require the optional components of Developer for System z. "rsed.envvars, RSE configuration file" in the Host Configuration Guide (SC23-7658) describes each variable that is defined in the sample file, where the following variables require special attention:
RSE is a Java application, which means that it is active in the z/OS UNIX environment. This promotes BPXPRMxx to become a crucial parmlib member, as it contains the parameters that control the z/OS UNIX environment and file systems. BPXPRMxx is described in the MVS Initialization and Tuning Reference (SA22-7592). The following directives are known to impact Developer for System z:
Value Range: nnnnn is a decimal value from 5 to 32767.
Default: 900
Value Range: nnnnn is a decimal value from 3 to 32767.
Default: 25
Value Range: nnnnnn is a decimal value from 0 to 100000.
Default: 200
Value Range: nnnnn is a decimal value from 0 to 32768.
Default: 1000
Value Range: nnnnn is a decimal value from 1 to 32767.
Default: 200
Value Range: nnnnn is a decimal value from 10485760 (10 Megabytes)
to 2147483647 (2 Gigabytes).
Default: 209715200 (200 Megabytes)
Value Range: nnnnnn is a decimal value from 3 to 524287.
Default: 64000
Value Range: nnnnn is a decimal value from 1 to 16777216.
Default: 40960
Use the SETOMVS or SET OMVS operator command to dynamically (until next IPL) increase or decrease the value of any of the previous BPXPRMxx variables. To make a permanent change, edit the BPXPRMxx member that will be used for IPLs. Refer to MVS System Commands (SA22-7627) for more information on these operator commands.
The following definitions are sub-parameters of the NETWORK statement.
Value Range: nnnnnnnn is a decimal value from 0 to 16777215.
Default: 100
Value Range: nnnn is a decimal value from 1 to 4000.
Default: If neither INADDRANYPORT or INADDRANYCOUNT
is specified, the default for INADDRANYCOUNT is 1000.
Otherwise, no ports are reserved (0).
The following definitions are recommended to be added to the EXEC card in the JCL of the Developer for System z servers.
The environment variables defined in FEJJCNFG are used by JES Job Monitor. The sample file that comes with Developer for System z is targeted at small to medium sized installations. "FEJJCNFG, JES Job Monitor configuration file" in the Host Configuration Guide (SC23-7658) describes each variable that is defined in the sample file, where the following variables require special attention:
IEASYSxx holds system parameters and is described in the MVS Initialization and Tuning Reference (SA22-7592). The following directives are known to impact Developer for System z:
Value Range: nnnnn is a decimal value from 0-32767. Note that the
sum of the values specified for the MAXUSER, RSVSTRT,
and RSVNONR system parameters cannot exceed 32767.
Default Value: 255
IVTPRMxx sets parameters for the Communication Storage Manager (CSM), and is described in the MVS Initialization and Tuning Reference (SA22-7592). The following directives are known to impact Developer for System z:
Value Range: maxfix is a value from 1024K to 2048M.
Default: 100M
Value Range: maxecsa is a value from 1024K to 2048M.
Default: 100M
The ASCHPMxx parmlib member contains scheduling information for the ASCH transaction scheduler, and is described in the MVS Initialization and Tuning Reference (SA22-7592). The following directives are known to impact Developer for System z:
Value Range: nnnnn is a decimal value from 1 to 64000.
Default: 1
Since user workloads can change the need for system resources, the system should be monitored regularly to measure resource usage so that Rational Developer for System z and system configurations can be adjusted in response to user requirements. The following commands can be used to aid in this monitoring process.
FEK004I RseDaemon: Max Heap Size=65MB and private AS Size=1,959MB
f rsed,appl=d p
BPXM023I (STCRSE)
ProcessId(16777456) Memory Usage(33%) Clients(4) Order(1)
f rsed,appl=d p,detail
BPXM023I (STCRSE)
ProcessId(33555087) ASId(002E) JobName(RSED8) Order(1)
PROCESS LIMITS: CURRENT HIGHWATER LIMIT
JAVA HEAP USAGE(%) 10 56 100
CLIENTS 0 25 30
MAXFILEPROC 83 103 64000
MAXPROCUSER 97 99 200
MAXTHREADS 9 14 1500
MAXTHREADTASKS 9 14 1500
f rsed,appl=d p,cpu
BPXM023I (STCRSE)
ProcessId(33555087) ASId(002E) JobName(RSED8) Order(1)
USERID THREAD-ID TCB@ ACC_TIME TAG
STCRSE 0EDE540000000000 005E6B60 822 1/ThreadPoolProcess
STCRSE 0EDE870000000001 005E69C8 001
STCRSE 0EDE980000000002 005E6518 1814
STCRSE 0EDEBA0000000003 005E66B0 2305
STCRSE 0EDECB0000000004 005E62F8 001
STCRSE 0EDEDC0000000005 005E60D8 001
STCRSE 0EDF860000000006 005C2BF8 628 6/ThreadPoolMonitor$Memory
UsageMonitor
STCRSE 0EDF970000000007 005C2D90 003 7/ThreadPoolMonitor
IBMUSER 0EE2C70000000024 005C08B0 050 38/JESMiner
IBMUSER 0EE2B60000000026 005C0690 004 40/FAMiner
IBMUSER 0EE30B0000000027 005C0250 002 41/LuceneMiner
IBMUSER 0EE31C0000000028 005C0030 002 42/CDTParserMiner
IBMUSER 0EE32D0000000029 005BDE00 002 43/MVSLuceneMiner
IBMUSER 0EE33E000000002A 005BDBE0 002 44/CDTMVSParserMiner
Most z/OS UNIX limits that are of interest for Developer for System z can be displayed using operator commands. Some commands even show the current usage and the high-water mark for a specific limit. Refer to MVS System Commands (SA22-7627) for more information on these commands.
d omvs,o
BPXO043I 13.10.16 DISPLAY OMVS 066
OMVS 000D ETC/INIT WAIT OMVS=(M7)
CURRENT UNIX CONFIGURATION SETTINGS:
MAXPROCSYS = 256 MAXPROCUSER = 16
MAXFILEPROC = 256 MAXFILESIZE = NOLIMIT
MAXCPUTIME = 1000 MAXUIDS = 200
MAXPTYS = 256
MAXMMAPAREA = 256 MAXASSIZE = 209715200
MAXTHREADS = 200 MAXTHREADTASKS = 1000
MAXCORESIZE = 4194304 MAXSHAREPAGES = 4096
IPCMSGQBYTES = 2147483647 IPCMSGQMNUM = 10000
IPCMSGNIDS = 500 IPCSEMNIDS = 500
IPCSEMNOPS = 25 IPCSEMNSEMS = 1000
IPCSHMMPAGES = 25600 IPCSHMNIDS = 500
IPCSHMNSEGS = 500 IPCSHMSPAGES = 262144
SUPERUSER = BPXROOT FORKCOPY = COW
STEPLIBLIST =
USERIDALIASTABLE=
SERV_LINKLIB = POSIX.DYNSERV.LOADLIB BPXLK1
SERV_LPALIB = POSIX.DYNSERV.LOADLIB BPXLK1
PRIORITYPG VALUES: NONE
PRIORITYGOAL VALUES: NONE
MAXQUEUEDSIGS = 1000 SHRLIBRGNSIZE = 67108864
SHRLIBMAXPAGES = 4096 VERSION = /
SYSCALL COUNTS = NO TTYGROUP = TTY
SYSPLEX = NO BRLM SERVER = N/A
LIMMSG = NONE AUTOCVT = OFF
RESOLVER PROC = DEFAULT
AUTHPGMLIST = NONE
SWA = BELOW
d omvs,l
BPXO051I 14.05.52 DISPLAY OMVS 904
OMVS 0042 ACTIVE OMVS=(69)
SYSTEM WIDE LIMITS: LIMMSG=SYSTEM
CURRENT HIGHWATER SYSTEM
USAGE USAGE LIMIT
MAXPROCSYS 1 4 256
MAXUIDS 0 0 200
MAXPTYS 0 0 256
MAXMMAPAREA 0 0 256
MAXSHAREPAGES 0 10 4096
IPCMSGNIDS 0 0 500
IPCSEMNIDS 0 0 500
IPCSHMNIDS 0 0 500
IPCSHMSPAGES 0 0 262144 *
IPCMSGQBYTES --- 0 262144
IPCMSGQMNUM --- 0 10000
IPCSHMMPAGES --- 0 256
SHRLIBRGNSIZE 0 0 67108864
SHRLIBMAXPAGES 0 0 4096
The command displays high-water marks and current usage for an individual process when the PID=processid keyword is also specified.
d,omvs,l,pid=16777456
BPXO051I 14.06.28 DISPLAY OMVS 645
OMVS 000E ACTIVE OMVS=(76)
USER JOBNAME ASID PID PPID STATE START CT_SECS
STCRSE RSED8 007E 16777456 67109106 HF---- 20.00.56 113.914
LATCHWAITPID= 0 CMD=java -Ddaemon.log=/var/rdz/logs -
PROCESS LIMITS: LIMMSG=NONE
CURRENT HIGHWATER PROCESS
USAGE USAGE LIMIT
MAXFILEPROC 83 103 256
MAXFILESIZE --- --- NOLIMIT
MAXPROCUSER 97 99 200
MAXQUEUEDSIGS 0 1 1000
MAXTHREADS 9 14 200
MAXTHREADTASKS 9 14 1000
IPCSHMNSEGS 0 0 500
MAXCORESIZE --- --- 4194304
MAXMEMLIMIT 0 0 16383P
d omvs,p
BPXO046I 14.35.38 DISPLAY OMVS 092
OMVS 000E ACTIVE OMVS=(33)
PFS CONFIGURATION INFORMATION
PFS TYPE DESCRIPTION ENTRY MAXSOCK OPNSOCK HIGHUSED
TCP SOCKETS AF_INET EZBPFINI 50000 244 8146
UDS SOCKETS AF_UNIX BPXTUINT 64 6 10
ZFS LOCAL FILE SYSTEM IOEFSCM
14:32.00 RECYCLING
HFS LOCAL FILE SYSTEM GFUAINIT
BPXFTCLN CLEANUP DAEMON BPXFTCLN
BPXFTSYN SYNC DAEMON BPXFTSYN
BPXFPINT PIPE BPXFPINT
BPXFCSIN CHAR SPECIAL BPXFCSIN
NFS REMOTE FILE SYSTEM GFSCINIT
PFS NAME DESCRIPTION ENTRY STATUS FLAGS
TCP41 SOCKETS EZBPFINI ACT CD
TCP42 SOCKETS EZBPFINI ACT
TCP43 SOCKETS EZBPFINI INACT SD
TCP44 SOCKETS EZBPFINI INACT
PFS PARM INFORMATION
HFS SYNCDEFAULT(60) FIXED(50) VIRTUAL(100)
CURRENT VALUES: FIXED(55) VIRTUAL(100)
NFS biod(6)
d omvs,pid=16777456
BPXO040I 15.30.01 DISPLAY OMVS 637
OMVS 000E ACTIVE OMVS=(76)
USER JOBNAME ASID PID PPID STATE START CT_SECS
STCRSE RSED8 007E 16777456 67109106 HF---- 20.00.56 113.914
LATCHWAITPID= 0 CMD=java -Ddaemon.log=/var/rdz/logs -
THREAD_ID TCB@ PRI_JOB USERNAME ACC_TIME SC STATE
0E08A00000000000 005E6DF0 OMVS .927 RCV FU
0E08F00000000001 005E6C58 .001 PTX JYNV
0E09300000000002 005E6AC0 7.368 PTX JYNV
0E0CB00000000008 005C2CF0 OMVS 1.872 SEL JFNV
0E192000000003CE 005A0B70 OMVS IBMUSER 14.088 POL JFNV
0E18D000000003CF 005A1938 IBMUSER .581 SND JYNV
Developer for System z uses z/OS UNIX file systems to store various types of data, such as logs and temporary files. Use the z/OS UNIX df command to see how many file descriptors are still available and how much free space is left before the next extent of the underlying HFS or zFS data set will be created.
$ df
Mounted on Filesystem Avail/Total Files Status
/tmp (OMVS.TMP) 1393432/1396800 4294967248 Available
/u/ibmuser (OMVS.U.IBMUSER) 1248/1728 4294967281 Available
/usr/lpp/rdz (OMVS.LPP.FEK) 3062/43200 4294967147 Available
/var (OMVS.VAR) 27264/31680 4294967054 Available
By default, Developer for System z tries to add 30 users to a single thread pool. However, our requirements indicate that the inactivity time-out will be active. Table 31 shows that this will add 1 thread per connected client. This thread is a timer thread, and thus constantly active. This will prevent RSE from putting 30 users in a single thread pool, as 10+30*(17+1)=550, and maximum.threads is set to 520 by default.
We could increase maximum.threads, but due to the requirement to have on average 20 MB of Java heap per user, we choose to lower maximum.clients to 25 (10+25*18 = 460). This keeps us within the default 512 MB maximum Java heap size (20*25 = 500).
With 25 clients per thread pool and the need to support 500 connections, we now know we will need 20 thread pool address spaces.
3 + 2*A + N*(x + y + z) + (2 + N*0.01)
3 + 2*20 + 500*1 + 200*1 + 300*1 + (2 + 500*0.01) = 1050
x + y + z
1 + 1 + 1 = 3
6 + 3*A + N*(x + y + z) + (10 + N*0.05)
6 + 3*20 + 500*2 + 200*1 + 300*0 + (10 + 500*0.05) = 1591
4 + 3*A
4 + 3*20 = 64
(x + y + z) + 5*s
(2 + 1 + 0) + 5*0 = 3
12 + N*(19 + x + y + z) + (20 + N*0.1)
12 + 25*(19 + 1 + 4 + 0) + (20 + 25*0.1) = 635
3 + N+ (20 + N*0.1)
3 + 500+ (20 + 500*0.1) = 573
4
4
500 + 3 = 503
The 3 extra user IDs are for STCJMON, STCDBM, and STCRSE, the Developer for System z started task user IDs.
not changed
not changed
This change is optional; RSE will start new thread pools as needed
1591 minimum, added extra buffer for tasks other than
Developer
for System z
64 minimum, added extra buffer in case the RSE thread pools
support less than the projected 25 clients
must be minimum 573 (for JES Job Monitor) if THREADSMAX in the
OMVS segment of user ID STCRSE is used to set the limit for RSE
(minimum 635)
must be minimum 573 (for JES Job Monitor) if THREADSMAX in the
OMVS segment of user ID STCRSE is used to set the limit for RSE
(minimum 635)
503 minimum, added extra buffer for tasks other than
Developer
for System z
not changed (200 MB system default), we use ASSIZEMAX in the OMVS
segment of user ID STCRSE
1050 minimum, added extra buffer for tasks other than
Developer
for System z
2 GB
After activating the system limits as documented in Defining limits, we can start monitoring the resource usage by Developer for System z to see if adjustment of some variables is needed. Figure 31 shows the resource usage after 499 users logged on. (The example in the figure shows just the logging on. No user actions are indicated in the example.)
F RSED,APPL=D P
BPXM023I (STCRSE)
ProcessId(83886168) Memory Usage(17%) Clients(25) Order(1)
ProcessId(91 ) Memory Usage(17%) Clients(25) Order(2)
ProcessId(122 ) Memory Usage(17%) Clients(25) Order(3)
ProcessId(16777348) Memory Usage(17%) Clients(25) Order(4)
ProcessId(16777358) Memory Usage(17%) Clients(25) Order(5)
ProcessId(16777368) Memory Usage(17%) Clients(25) Order(6)
ProcessId(16777378) Memory Usage(17%) Clients(25) Order(7)
ProcessId(16777388) Memory Usage(17%) Clients(25) Order(8)
ProcessId(16777398) Memory Usage(17%) Clients(25) Order(9)
ProcessId(33554622) Memory Usage(17%) Clients(25) Order(10)
ProcessId(16777416) Memory Usage(17%) Clients(25) Order(11)
ProcessId(16777426) Memory Usage(17%) Clients(25) Order(12)
ProcessId(16777436) Memory Usage(9%) Clients(25) Order(13)
ProcessId(16777446) Memory Usage(17%) Clients(25) Order(14)
ProcessId(16777456) Memory Usage(17%) Clients(25) Order(15)
ProcessId(16777466) Memory Usage(17%) Clients(25) Order(16)
ProcessId(16777476) Memory Usage(17%) Clients(25) Order(17)
ProcessId(16777487) Memory Usage(17%) Clients(25) Order(18)
ProcessId(16777497) Memory Usage(17%) Clients(25) Order(19)
ProcessId(16777507) Memory Usage(16%) Clients(24) Order(20)
F RSED,APPL=D P,D
BPXM023I (STCRSE)
ProcessId(83886168) ASId(0022) JobName(RSED857 ) Order(1)
PROCESS LIMITS: CURRENT HIGHWATER LIMIT
JAVA HEAP USAGE(%) 17 17 100
CLIENTS 25 25 25
MAXFILEPROC 365 366 64000
MAXPROCUSER 64 64 100
MAXTHREADS 362 363 1500
MAXTHREADTASKS 363 363 1500
TASID
Jobname Cpu time Storage EXCP
-------- ----------- ------- ----------
JMON 0.00 1780 73
RSED 5.88 95.2M 41958
RSED1 8.26 190.1M 58669
RSED1 8.17 187.0M 58605
RSED2 8.06 185.3M 58653
RSED2 8.19 183.1M 60209
RSED3 8.12 189.1M 58650
RSED3 8.03 186.7M 58590
RSED4 8.15 188.2M 58646
RSED4 5.50 182.5M 58585
RSED5 7.72 184.4M 58631
RSED5 7.82 184.1M 58576
RSED6 7.14 184.1M 58622
RSED6 6.27 186.9M 58583
RSED7 5.17 185.1M 58804
RSED7 6.57 185.2M 58621
RSED7 5.86 182.8M 58565
RSED8 0.36 1560 2459
RSED8 7.94 184.1M 58615
RSED8 7.45 181.8M 58548
RSED9 8.16 190.6M 58802
RSED9 7.62 183.8M 58610
RSED9 7.36 177.7M 57478
z/OS is a highly customizable operating system, and (sometimes small) system changes can have a huge impact on the overall performance. This chapter highlights some of the changes that can be made to improve the performance of Developer for System z.
Refer to the MVS Initialization and Tuning Guide (SA22-7591) and UNIX System Services Planning (GA22-7800) for more information on system tuning.
Refer to UNIX System Services Planning (GA22-7800) to learn more about zFS.
Each z/OS UNIX process that has a STEPLIB that is propagated from parent to child or across an exec will consume about 200 bytes of Extended Common Storage Area (ECSA). If no STEPLIB environment variable is defined, or when it is defined as STEPLIB=CURRENT, z/OS UNIX propagates all currently active TASKLIB, STEPLIB, and JOBLIB allocations during a fork(), spawn(), or exec() function.
Developer for System z has a default of STEPLIB=NONE coded in rsed.envvars, as described in rsed.envvars, configuration file. For the reasons mentioned previously, you should not change this directive and you should place the targeted data sets in LINKLIST or LPA (Link Pack Area) instead.
Certain system libraries and load modules are heavily used by z/OS UNIX and application development activities. Improving access to these, such as adding them to the Link Pack Area (LPA) can improve your system performance. Refer to MVS Initialization and Tuning Reference (SA22-7592) for more information on changing the SYS1.PARMLIB members described as follows:
When C programs (including the z/OS UNIX shell) are run, they frequently use routines from the Language Environment (LE) runtime library. On average, about 4 MB of the runtime library are loaded into memory for every address space running a LE-enabled program, and copied on every fork.
CEE.SCEELPA
The CEE.SCEELPA data set contains a subset of the LE runtime routines, which are heavily used by z/OS UNIX. You should add this data set to SYS1.PARMLIB(LPALSTxx) for maximum performance gain. By doing so, the modules are read from disk only once and are stored in a shared location.
LPA ADD MASK(*) DSNAME(CEE.SCEELPA)
It is also advised to place the LE runtime libraries CEE.SCEERUN and CEE.SCEERUN2 in LINKLIST, by adding the data sets to SYS1.PARMLIB(LNKLSTxx) or SYS1.PARMLIB(PROGxx). This eliminates z/OS UNIX STEPLIB overhead and there is reduced input/output due to management by LLA and VLF, or similar products.
If you decide not to put these libraries in LINKLIST, then you must set up the appropriate STEPLIB statement in rsed.envvars, as described in rsed.envvars, configuration file. Although this method always uses additional virtual storage, you can improve performance by defining the LE runtime libraries to LLA or a similar product. This reduces the I/O that is needed to load the modules.
On systems where application development is the primary activity, performance may also benefit if you put the linkage editor into dynamic LPA, by adding the following lines to SYS1.PARMLIB(PROGxx):
LPA ADD MODNAME(CEEBINIT,CEEBLIBM,CEEEV003,EDCZV) DSNAME(CEE.SCEERUN)
LPA ADD MODNAME(IEFIB600,IEFXB603) DSNAME(SYS1.LINKLIB)
For C/C++ development, you can also add the CBC.SCCNCMP compiler data set to SYS1.PARMLIB(LPALSTxx).
The preceding statements are samples of possible LPA candidates, but the needs at your site may vary. Refer to Language Environment Customization (SA22-7564) for information on putting other LE load modules into dynamic LPA. Refer to UNIX System Services Planning (GA22-7800) for more information on putting C/C++ compiler load modules into dynamic LPA.
Each site has specific needs, and can customize the z/OS operating system to get the most out of the available resources to meet those needs. With workload management, you define performance goals and assign a business importance to each goal. You define the goals for work in business terms, and the system decides how much resource, such as CPU and storage, should be given to the work to meet its goal.
Developer for System z performance can be balanced by setting the correct goals for its processes. Some general guidelines are listed as follows:
Refer to MVS Planning Workload Management (SA22-7602) for more information about this subject.
With a fixed-size heap, no heap expansion or contraction occurs and this can lead to significant performance gains in some situations. However, using a fixed-size heap is usually not a good idea, because it delays the start of garbage collection until the heap is full, at which point it will be a major task. It also increases the risk of fragmentation, which requires a heap compaction. Therefore, use fixed-size heaps only after proper testing or under the direction of the IBM support center. Refer to Java Diagnostics Guide (SC34-6650) for more information on heap sizes and garbage collection.
The initial and maximum heap size of a z/OS Java Virtual Machine (JVM) can be set with the -Xms (initial) and -Xmx (maximum) Java command-line options.
In Developer for System z, Java command-line options are defined in the _RSE_JAVAOPTS directive of rsed.envvars, as described in "Defining extra Java startup parameters with _RSE_JAVAOPTS" in the Host Configuration Guide (SC23-7658).
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Xms128m -Xmx128m"
The -Xquickstart option can be used for improving startup time of some Java applications. -Xquickstart causes the JIT (Just In Time) compiler to run with a subset of optimizations; that is, a quick compile. This quick compile allows for improved startup time.
The -Xquickstart option is appropriate for shorter running applications, especially those where execution time is not concentrated into a small number of methods. -Xquickstart can degrade performance if it is used on longer-running applications that contain hot methods.
_RSE_JAVAOPTS="$_RSE_JAVAOPTS -Xquickstart"
The IBM Java Virtual Machine (JVM) version 5 and higher allows you to share bootstrap and application classes between JVMs by storing them in a cache in shared memory. Class sharing reduces the overall virtual memory consumption when more than one JVM shares a cache. Class sharing also reduces the startup time for a JVM after the cache has been created.
The shared class cache is independent of any active JVM and persists beyond the lifetime of the JVM that created the cache. Because the shared class cache persists beyond the lifetime of any JVM, the cache is updated dynamically to reflect any modifications that might have been made to JARs or classes on the file system.
The overhead to create and populate a new cache is minimal. The JVM startup cost in time for a single JVM is typically between 0 and 5% slower compared with a system not using class sharing, depending on how many classes are loaded. JVM startup time improvement with a populated cache is typically between 10% and 40% faster compared with a system not using class sharing, depending on the operating system and the number of classes loaded. Multiple JVMs running concurrently will show greater overall startup time benefits.
Refer to the Java SDK and Runtime Environment User Guide to learn more about class sharing.
_RSE_CLASS_OPTS=-Xshareclasses:name=RSE,groupAccess,nonFatal
#_RSE_CLASS_OPTS="$_RSE_CLASS_OPTS -Xscmx6m
_RSE_JAVAOPTS="$_RSE_JAVAOPTS $_RSE_CLASS_OPTS"
The maximum theoretical shared cache size is 2 GB. The size of cache you can specify is limited by the amount of physical memory and swap space available to the system. Because the virtual address space of a process is shared between the shared class cache and the Java heap, increasing the maximum size of the Java heap will reduce the size of the shared class cache you can create.
Access to the shared class cache is limited by operating system permissions and Java security permissions.
By default, class caches are created with user-level security, so only the user that created the cache can access it. On z/OS UNIX, there is an option, groupAccess, which gives access to all users in the primary group of the user that created the cache. However, regardless of the access level used, a cache can only be destroyed by the user that created it or by a root user (UID 0).
Refer to Java SDK and Runtime Environment User Guide to learn more about extra security options using a Java SecurityManager.
These settings affect the amount of shared memory pages available to the JVM. The shared page size for a 31-bit z/OS UNIX system service is fixed at 4 KB. Shared classes try to create a 16 MB cache by default. Therefore set IPCSHMMPAGES greater than 4096.
If you set a cache size using -Xscmx, the JVM will round up the value to the nearest megabyte. You must take this into account when setting IPCSHMMPAGES on your system.
These settings affect the amount of semaphores available to UNIX processes. Shared classes use IPC semaphores to communicate between the JVMs.
The shared class cache requires disk space to store identification information about the caches that exist on the system. This information is stored in /tmp/javasharedresources. If the identification information directory is deleted, the JVM cannot identify the shared classes on the system and must recreate the cache.
$ java -Xshareclasses:listAllCaches
Shared Cache OS shmid in use Last detach time
RSE 401412 0 Mon Jun 18 17:23:16 2007
Could not create the Java virtual machine.
$ java -Xshareclasses:name=RSE,printStats
Current statistics for cache "RSE":
base address = 0x0F300058
end address = 0x0F8FFFF8
allocation pointer = 0x0F4D2E28
cache size = 6291368
free bytes = 4355696
ROMClass bytes = 1912272
Metadata bytes = 23400
Metadata % used = 1%
# ROMClasses = 475
# Classpaths = 4
# URLs = 0
# Tokens = 0
# Stale classes = 0
% Stale classes = 0%
Cache is 30% full
Could not create the Java virtual machine.
$ java -Xshareclasses:name=RSE,destroy
JVMSHRC010I Shared Cache "RSE" is destroyed
Could not create the Java virtual machine.
Developer for System z clients version 8.0.1 and higher can pull client configuration files and product update information from the host when they connect, ensuring that all clients have common settings and that they are up-to-date.
Since version 8.0.3, the client administrator can create multiple client configuration sets and multiple client update scenarios to fit the needs of different developer groups. This allows users to receive a customized setup, based on criteria like membership of an LDAP group or permit to a security profile.
z/OS Projects can be defined individually through the z/OS Projects perspective on the client, or z/OS Projects can be defined centrally on the host and propagated to the client on an individual user basis. These "host-based projects" look and function exactly like projects defined on the client except that their structure, members, and properties cannot be modified by the client, and they are accessible only when connected to the host.
pushtoclient.properties tells the client if these functions are enabled, and where the related data is stored. See “(Optional) pushtoclient.properties, Host-based client control” in the Host Configuration Guide (SC23-7658) for more information.
See the Developer for System z Information Center (http://www-01.ibm.com/support/knowledgecenter/SSQ2R2_9.1.0/com.ibm.etools.getstart.wsentdev.doc/kc_version_welcome_rdz.html) for details about how the client administrator and the development project manager can perform the tasks assigned to them.
Push-to-client is designed to store system-specific data per system, while maintaining common (global) data on a single system (the primary system) to reduce management effort. The primary system is identified by the primary.system directive in pushtoclient.properties. The default is false.
Ensure you have one, and only one, system defined as the primary system. Developer for System z client administrators are not able to export global configuration data unless the target system is a primary system. Developer for System z clients might show erratic behavior when connecting to multiple primary systems with out-of-sync configurations.
The only-one rule does not apply when multiple systems share the Developer for System z configuration (/etc/rdz) and push-to-client metadata (/var/rdz/pushtoclient). Since the configuration is shared, all systems involved are identified as the primary system. But as long as all systems also share the metadata, this duplication is not an issue.
The pushtoclient.folder directive in pushtoclient.properties identifies the base directory where the push-to-client metadata is stored. The default is /var/rdz/pushtoclient.
The base directory holds the root push-to-client configuration file, keymapping.xml. All other metadata is in subdirectories.
Most subdirectories are created dynamically when the client administrator exports the push-to-client workspace configuration. These subdirectories group the metadata by subject, such as mappings and preferences. As more Developer for System z client components become eligible to be managed by push-to-client, more subdirectories are created dynamically. See the export wizard in the Developer for System z client (File > Export… > Rational Developer for System z > Configuration Files) to learn what is stored in these subdirectories.
See “Customization setup” in the “Basic customization” chapter of the Host Configuration Guide (SC23-7658) for more information about the creation of these subdirectories.
By default (see the file.permission directive in pushtoclient.properties), all files and directories created in the base directory receive permission bitmask 775 (rwxrwxr-x), which allows the owner and the owner's default group read and write access to the directory structure and the files within. Everyone else has only read access to the directory structure and the files within.
It is important that the correct owner UID (user ID) and GID (group ID) are set for these directories before starting with the push-to-client setup.
ADDGROUP RDZADMIN OWNER(IBMUSER) SUPGROUP(SYS1) –
DATA('RATIONAL DEVELOPER FOR SYSTEM Z - CLIENT ADMIN')
ALTGROUP RDZADMIN OMVS(GID(2))
CONNECT RDZADM1 GROUP(RDZADMIN) AUTH(USE)
ALTUSER RDZADM1 DFLTGRP(RDZADMIN) OMVS(UID(6))
chown –R rdzadm1:rdzadmin /var/rdz/pushtoclient
chmod –R 775 /var/rdz/pushtoclient
See Security Server RACF Command Language Reference (SA22-7687) for more information about the sample RACF commands. See UNIX System Services Command Reference (SA22-7802) for more information about the sample z/OS UNIX commands. See z/OS UNIX directory structure for additional information.
The push-to-client metadata uses a reasonably small amount of disk space in z/OS UNIX, because the bulk of the metadata is UTF-8 encoded XML files. Note that the product code used for the client update scenarios can be stored anywhere on the network; it does not have to be stored in z/OS UNIX, because the related push-to-client metadata (called response files) point the client to the correct location.
When a Developer for System z client (version 8.0.1 and higher) connects to the host, it reads the definitions in pushtoclient.properties. If directive config.enabled is enabled, the client compares its current configuration to the definitions in the push-to-client metadata. If differences are found, the client starts a wizard that pulls the required data and activates the setup as dictated by push-to-client.
The reject.config.updates directive in pushtoclient.properties controls whether a user is allowed to reject the configuration updates push-to-client is about to deliver.
A Developer for System z client (version 8.0.1 and higher) has a wizard, to be used by the client administrator, that can export the current configuration, which in turn is imported by all Developer for System z clients through push-to-client. Note that this function is available in all clients, so you should ensure that only client administrators have write permission to the z/OS UNIX directories that hold the push-to-client metadata (/var/rdz/pushtoclient).
Version 8.0.3 or higher is required for both client and host to enable group support, as documented in Multiple developer groups.
When a Developer for System z client (version 8.0.1 and higher) connects to the host, it reads the definitions in pushtoclient.properties. If directive product.enabled is enabled, the client compares its current product version to the definitions in the push-to-client metadata. If differences are found, the client starts a wizard that pulls the required data and activates the setup as dictated by push-to-client.
The reject.product.updates directive in pushtoclient.properties controls whether a user is allowed to reject the product updates push-to-client is about to deliver.
Version 8.0.3 or higher is required for both client and host to enable group support, as documented in Multiple developer groups.
Since version 8.0.3, the client administrator can create multiple client configuration sets and multiple client update scenarios to fit the needs of different developer groups. This allows users to receive a customized setup, based on criteria like membership of an LDAP group or permit to a security profile.
Support for multiple developer groups, each with their own client configuration and client update requirements, is enabled by assigning the desired value to the related directives (config.enabled and product.enabled) in pushtoclient.properties, as shown in Table 36.
*.enabled value | Function enabled | Multiple groups supported |
---|---|---|
False | No | No |
True | Yes | No |
LDAP | Yes | Yes, based on membership of LDAP groups FEK.PTC.*.ENABLED.sysname.devgroup |
SAF | Yes | Yes, based on permit to security profiles FEK.PTC.*.ENABLED.sysname.devgroup |
Note that when the function is enabled (this includes the TRUE value), developers are always part of a default group. A developer can be part of none, one, or multiple additional groups.
Rejecting the updates can also be made conditional, as shown in Table 37.
reject.*.updates value | Function enabled |
---|---|
False | No |
True | Yes |
LDAP | Depends on LDAP group membership FEK.PTC.REJECT.*.UPDATES.sysname.** |
SAF | Depends on permit to security profile FEK.PTC.REJECT.*.UPDATES.sysname.** |
Note that the directives in pushtoclient.properties work independently from each other. You can assign any supported value to any directive. There is no requirement to keep settings alike.
See LDAP-based group selection and SAF-based group selection for details about the required setup for the respective function. See “(Optional) pushtoclient.properties, Host-based client control” in the Host Configuration Guide (SC23-7658) for more information about enabling multiple group support.
When the *.enabled function is enabled (this includes the TRUE value) in pushtoclient.properties, developers are always part of a default group for the related function. A developer can be part of none, one, or multiple additional groups.
To limit the complexity of applying changes defined in multiple groups, Developer for System z limits which definitions will be used, based on a selection made by the user.
Additional groups | Definitions used |
---|---|
None | Default |
One | Default or (default + group) |
Multiple | Default or (default + 1 group) |
Even though a developer can be part of multiple groups simultaneously, the developer’s active workspace cannot. The active workspace must be bound to a specific configuration group (which can be the default group) and a specific product group (which can be the default group) to receive configuration or product updates. Once the bind is done, it cannot be undone. A new workspace must be created if a new group binding is required.
When a workspace that has no configuration group binding connects to the host, and config.enabledindicates the push-to-client function is active, Developer for System z queries all configuration groups to determine to which groups the user belongs to and prompts the user to select a group. Upon successive connections, only the selected group is queried to see if the group membership is still valid.
config.enabled | Workspace bound to this configuration update group |
---|---|
False | None |
True | Default |
LDAP | Default or Group (after prompting) |
SAF | Default or Group (after prompting) |
When a workspace that has no product group binding connects to the host, and product.enabled indicates the push-to-client function is active, Developer for System z queries all product groups to determine to which groups the user belongs to and prompts the user to select a group. Upon successive connections, only the selected group is queried to see if the group membership is still valid.
product.enabled | Workspace bound to this product update group |
---|---|
False | None |
True | Default |
LDAP | Default or Group (after prompting) |
SAF | Default or Group (after prompting) |
The reject.*.updates directives can work with and without group definitions. If groups are used for reject.*.updates, then the group-binding of the related *.enabled directive is used. When an update is present, Developer for System z determines if the user is allowed to reject the update, and acts accordingly.
Group support for the reject.*.updates directives is new in version 9.1.0, and requires that both Developer for System z host and client are at version 9.1.0 or later. The support changes how the LDAP and SAF keywords are processed.
Before version 9.1.0, being on the access list for FEK.PTC.REJECT.*.UPDATES.sysname was sufficient to reject an update, regardless of workspace group binding. Since version 9.1.0, FEK.PTC.REJECT.*.UPDATES.sysname is used only for rejecting updates by workspaces bound to the default group. Workspaces bound to a group require you to be on the access list for FEK.PTC.REJECT.*.UPDATES.sysname.groupname to reject updates.
Initial product customization creates the grouping/ directory in /var/rdz/pushtoclient/. The client administrator is responsible for adding the <devgroup>/ directories to /var/rdz/pushtoclient/grouping/.
Note that during initial product customization, the projects/, install/, and install/responsefiles/ directories are created in /var/rdz/pushtoclient/. The client administrator must repeat these make-directory actions in /var/rdz/pushtoclient/grouping/<devgroup>/ if there is a need for group-specific product upgrade scenarios or group-specific host-based projects.
The following sample z/OS UNIX command sequence creates the subdirectories with the correct permission bitmask. The commands should be executed by the client administrator to avoid ownership problems.
saved_umask=$(umask)
umask 0000
cd /var/rdz/pushtoclient/grouping/
mkdir –m775 <devgroup>
cd <devgroup>
mkdir –m775 install
mkdir –m775 install/responsefiles
mkdir –m775 projects
umask $saved_umask
See UNIX System Services Command Reference (SA22-7802) for more information about the sample z/OS UNIX commands.
/var/rdz/pushtoclient/grouping/<devgroup>
directory
for each push-to-client group.Although LDAP (Lightweight Directory Access Protocol) is the name of a TCP/IP based protocol, it is commonly used to describe a set of distributed directory services. Like a database, a directory is a structured collection of records. Developer for System z can use an LDAP server as a simple hierarchical database, where groups hold one or more members.
When using definitions in your LDAP server as selection mechanism (the LDAP value is specified for directives in pushtoclient.properties), Developer for System z verifies membership of the group names listed in Table 41 to determine which developer groups the user belongs to, and whether a user is allowed to reject updates.
Group name (cn=) | Result |
---|---|
FEK.PTC.CONFIG.ENABLED.sysname.devgroup | Client accepts configuration updates for the specified group |
FEK.PTC.PRODUCT.ENABLED.sysname.devgroup | Client accepts product updates for the specified group |
FEK.PTC.REJECT.CONFIG.UPDATES.sysname | User can reject configuration updates when the workspace is bound to the default group |
FEK.PTC.REJECT.CONFIG.UPDATES.sysname.devgroup | User can reject configuration updates when the workspace is bound to the specified group |
FEK.PTC.REJECT.PRODUCT.UPDATES.sysname | User can reject product updates when the workspace is bound to the default group |
FEK.PTC.REJECT.PRODUCT.UPDATES.sysname.devgroup | User can reject product updates when the workspace is bound to the specified group |
The devgroup value matches the group name assigned to a specific group of developers. Note that the group name is visible on Developer for System z clients.
The sysname value matches the system name of the target system.
A user can select to bind a workspace to the default group for configuration updates if config.enabled in pushtoclient.properties is set to SAF or LDAP. If config.enabled is set to TRUE, the workspace is automatically bound to the default group.
A user can select to bind a workspace to the default group for product updates if product.enabled in pushtoclient.properties is set to SAF or LDAP. If product.enabled is set to TRUE, the workspace is automatically bound to the default group.
Group support for the reject.*.updates directives is new in version 9.1.0, and changes how the LDAP and SAF keywords are processed.
Figure 32 is a sample LDAP definition for a group and user, expressed in LDIF format.
# Group Definition
dn: cn=FEK.PTC.CONFIG.ENABLED.CDFMVS08.GROUPA,o=PTC,c=DeveloperForZ
objectClass: groupOfUniqueNames
objectClass: top
cn: FEK.PTC.CONFIG.ENABLED.CDFMVS08.GROUPA
description: Project A
uniqueMember: uid=mborn,ou=Users,dc=example,dc=com
# User Definition
dn: uid=mborn,ou=Users,dc=example,dc=com
objectClass: organizationalPerson
objectClass: person
objectClass: inetOrgPerson
objectClass: uidObject
objectClass: top
cn: May Born
sn: Born
uid: mborn
facsimiletelephonenumber: +1 800 982 6883
givenname: May
mail: mborn@example.com
ou: Users
There is a wide selection of commercial and free LDAP servers available. One example is the IBM Tivoli® Directory Server (http://www-01.ibm.com/software/tivoli/products/directory-server/). There is also a wide selection of command-line and GUI-based tools to manage an LDAP server.
As mentioned in LDAP schema, each user must be defined to the LDAP server. To reduce management effort, it is best to place the push-to-client schema on an LDAP server that already has access to all user definitions. For example, you can use IBM Tivoli Directory Server active on z/OS using an SDBM database (which is a wrapper for your security database).
Depending on site policies, the push-to-client schema on the LDAP server might be managed by the client administrator. This arrangement reduces collaboration needs, and possible delays and communication errors.
An argument in favor of LDAP management by the client administrator is that the push-to-client schema does not hold anything confidential or security-related. When user definitions are available to the LDAP server through other schemas, the Developer for System z LDAP objects just determine which choices a developer has in selecting a workspace layout and automatic Developer for System z client product upgrades.
Any database server that supports the LDAP protocol can be used to host the Developer for System z push-to-client schema. Therefore, Developer for System z allows you to specify the information needed to connect to the LDAP server. You can also specify the suffix that makes the database unique within the LDAP server.
rsed.envvars directive | Default |
---|---|
_RSE_LDAP_SERVER | Local host system |
_RSE_LDAP_PORT | 389 |
_RSE_LDAP_PTC_GROUP_SUFFIX | "O=PTC,C=DeveloperForZ" |
Assume a company has Developer for System z active on system CDFMVS08. IBM Tivoli Directory Server, also active on CDFMVS08, is used as LDAP server. The LDAP server is configured as described in Adding push-to-client back-end to LDAP.
Each group of developers requires specific client configuration files, and all developers are subject to the same client version control. Unlike client administrators, developers are not allowed to reject any of the changes push-to-client presents.
The client administrator and LDAP administrator agreed on using group names BANKING and INSURANCE for the configuration updates.
# filename ds.conf
# restart GLDSRV started task to pick up changes
# global section
adminDN "cn=LDAP admin"
adminPW password
listen ldap://:389
schemaPath /etc/ldap
# SDBM back-end section (RACF)
database SDBM GLDBSD31/GLDBSD64
suffix "cn=RACF,o=IBM,c=US"
# LDBM back-end section (z/OS UNIX files)
database LDBM GLDBLD31/GLDBLD64 LDBM-RDZ
suffix "o=PTC,c=DeveloperForZ"
databaseDirectory /var/ldap/ldbm/rdz
mkdir -p /var/ldap/ldbm/rdz
ldapmodify -D "cn=LDAP admin" -w password -f
/usr/lpp/ldap/etc/schema.user.ldif
ldapmodify -D "cn=LDAP admin" -w password -f
/usr/lpp/ldap/etc/schema.IBM.ldif
ldapadd -D "cn=LDAP admin" -w password -f
/u/ibmuser/ptc_root.ldif
where /u/ibmuser/ptc_root.ldif holds
the following:dn: o=PTC,c=DeveloperForZ
objectclass: top
objectclass: organization
o: PTC
Add the different LDAP group objects to the schema, and make the client administrator part of each of them. The user definition for the RDZADM1 user ID is pulled from the RACF schema.
ldapadd -D "cn=LDAP admin" -w password -f /u/ibmuser/ptc_setup.ldif
# banking workspace configuration
dn: cn=FEK.PTC.CONFIG.ENABLED.CDFMVS08.BANKING,o=PTC,c=DeveloperForZ
objectclass: groupOfUniqueNames
cn: FEK.PTC.CONFIG.ENABLED.CDFMVS08.BANKING
description: Developer for System z push-to-client
# give client administrator access
uniqueMember: racfID=RDZADM1,profileType=user,cn=RACF,o=IBM,c=US
# insurance workspace configuration
dn: cn=FEK.PTC.CONFIG.ENABLED.CDFMVS08.INSURANCE,o=PTC,c=DeveloperForZ
objectclass: groupOfUniqueNames
cn: FEK.PTC.CONFIG.ENABLED.CDFMVS08.INSURANCE
description: Developer for System z push-to-client
# give client administrator access
uniqueMember: racfID=RDZADM1,profileType=user,cn=RACF,o=IBM,c=US
# reject configuration updates
dn: cn=FEK.PTC.REJECT.CONFIG.UPDATES.CDFMVS08,o=PTC,c=DeveloperForZ
objectclass: groupOfUniqueNames
cn: FEK.PTC.REJECT.CONFIG.UPDATES.CDFMVS08
description: Developer for System z push-to-client
# give client administrator access
uniqueMember: racfID=RDZADM1,profileType=user,cn=RACF,o=IBM,c=US
# reject product updates
dn: cn=FEK.PTC.REJECT.PRODUCT.UPDATES.CDFMVS08,o=PTC,c=DeveloperForZ
objectclass: groupOfUniqueNames
cn: FEK.PTC.REJECT.PRODUCT.UPDATES.CDFMVS08
description: Developer for System z push-to-client
# give client administrator access
uniqueMember: racfID=RDZADM1,profileType=user,cn=RACF,o=IBM,c=US
Add the developers to the LDAP group objects. The user definitions for the user IDs are pulled from the RACF schema.
ldapmodify -D "cn=LDAP admin" -w password -f /u/ibmuser/ptc_add.ldif
where /u/ibmuser/ptc_add.ldif holds
the following:# banking workspace configuration
dn: cn=FEK.PTC.CONFIG.ENABLED.CDFMVS08.BANKING,o=PTC,c=DeveloperForZ
changeType: modify
add: uniqueMember
uniqueMember: racfID=BNK010,profileType=user,cn=RACF,o=IBM,c=US
uniqueMember: racfID=BNK011,profileType=user,cn=RACF,o=IBM,c=US
uniqueMember: racfID=BNK012,profileType=user,cn=RACF,o=IBM,c=US
uniqueMember: racfID=BNK013,profileType=user,cn=RACF,o=IBM,c=US
uniqueMember: racfID=BNK014,profileType=user,cn=RACF,o=IBM,c=US
# insurance workspace configuration
dn: cn=FEK.PTC.CONFIG.ENABLED.CDFMVS08.INSURANCE,o=PTC,c=DeveloperForZ
changeType: modify
add: uniqueMember
uniqueMember: racfID=INS010,profileType=user,cn=RACF,o=IBM,c=US
uniqueMember: racfID=INS011,profileType=user,cn=RACF,o=IBM,c=US
uniqueMember: racfID=INS012,profileType=user,cn=RACF,o=IBM,c=US
uniqueMember: racfID=INS013,profileType=user,cn=RACF,o=IBM,c=US
uniqueMember: racfID=INS014,profileType=user,cn=RACF,o=IBM,c=US
# BANKING and INSURANCE have different configuration needs
config.enabled=LDAP
# everyone receives product updates
product.enabled=TRUE
# only RDZADMIN can reject configuration updates
reject.config.updates=LDAP
# only RDZADMIN can reject product updates
reject.product.updates=LDAP
Because there are no individualized product upgrade scenarios, the client administrator does not need to create or update the install/ and install/responsefiles/ subdirectories in /var/rdz/pushtoclient/grouping/<devgroup>.
The client administrator must create the response files needed for product updates in the default-group directory, /var/rdz/pushtoclient/install/responsefiles/.
SAF (Security Access Facility) is an interface to access any z/OS security product. Developer for System z can use this interface to query your security product and retrieve push-to-client related information.
When using definitions in your security database as selection mechanism (the SAF value is specified for directives in pushtoclient.properties), Developer for System z verifies access permits to the profiles listed in Table 42 to determine which developer groups the user belongs to, and whether a user is allowed to reject updates.
FACILITY profile | Fixed length | Required access | Result |
---|---|---|---|
FEK.PTC.CONFIG.ENABLED. |
23 | READ | Client accepts configuration updates for the specified group |
FEK.PTC.PRODUCT.ENABLED. |
24 | READ | Client accepts product updates for the specified group |
FEK.PTC.REJECT.CONFIG. |
30 | READ | User can reject configuration updates when the workspace is bound to the default group |
FEK.PTC.REJECT.CONFIG. UPDATES.sysname.devgroup | 30 | READ | User can reject configuration updates when the workspace is bound to the specified group |
FEK.PTC.REJECT.PRODUCT. |
31 | READ | User can reject product updates when the workspace is bound to the default group |
FEK.PTC.REJECT.PRODUCT. UPDATES.sysname.devgroup | 31 | READ | User can reject product updates when the workspace is bound to the specified group |
The devgroup value matches the group name assigned to a specific group of developers. Note that the group name is visible on Developer for System z clients.
The sysname value matches the system name of the target system.
A user can select to bind a workspace to the default group for configuration updates if config.enabled in pushtoclient.properties is set to SAF or LDAP. If config.enabled is set to TRUE, the workspace is automatically bound to the default group.
A user can select to bind a workspace to the default group for product updates if product.enabled in pushtoclient.properties is set to SAF or LDAP. If product.enabled is set to TRUE, the workspace is automatically bound to the default group.
The “Fixed length” column documents the length of the fixed part of the related security profile.
By default, Developer for System z expects the FEK.* profiles to be in the FACILITY security class. Note that profiles in the FACILITY class are limited to 39 characters. If the sum of the length of the fixed profile part (FEK.PTC.<key>.) and the length of the site-specific profile part (sysname or sysname.devgroup) exceeds this number, you can place the profiles in another class and instruct Developer for System z to use this class instead. To do that, uncomment _RSE_FEK_SAF_CLASS in rsed.envvars and provide the desired class name.
Each group of developers requires specific client configuration files, and all developers are subject to the same client version control. Unlike client administrators, developers are not allowed to reject any of the changes push-to-client presents. The reject rule is valid for all systems, in preparation for future expansion.
The client and security administrator agree to use push-to-client group names BANKING and INSURANCE for the configuration updates.
# allow RDZADMIN and DEVBANK to select push-to-client group BANKING
RDEFINE XFACILIT (FEK.PTC.CONFIG.ENABLED.CDFMVS08.BANKING) –
UACC(NONE) DATA('RATIONAL DEVELOPER FOR SYSTEN Z - PUSH-TO-CLIENT')
PERMIT FEK.PTC.CONFIG.ENABLED.CDFMVS08.BANKING CLASS(XFACILIT) –
ID(RDZADMIN DEVBANK) ACCESS(READ)
# allow RDZADMIN and DEVINSUR to select push-to-client group INSURANCE
RDEFINE XFACILIT (FEK.PTC.CONFIG.ENABLED.CDFMVS08.INSURANCE) –
UACC(NONE) DATA('RATIONAL DEVELOPER FOR SYSTEN Z - PUSH-TO-CLIENT')
PERMIT FEK.PTC.CONFIG.ENABLED.CDFMVS08.INSURANCE CLASS(XFACILIT) –
ID(RDZADMIN DEVINSUR) ACCESS(READ)
# RDZADMIN can reject configuration updates on any system and for any group
RDEFINE XFACILIT (FEK.PTC.REJECT.CONFIG.UPDATES.**) –
UACC(NONE) DATA('RATIONAL DEVELOPER FOR SYSTEN Z - PUSH-TO-CLIENT')
PERMIT FEK.PTC.REJECT.CONFIG.UPDATES.** CLASS(XFACILIT) –
ID(RDZADMIN) ACCESS(READ)
# RDZADMIN can reject product updates on any system system and for any group
RDEFINE XFACILIT (FEK.PTC.REJECT.PRODUCT.UPDATES.**) –
UACC(NONE) DATA('RATIONAL DEVELOPER FOR SYSTEN Z - PUSH-TO-CLIENT')
PERMIT FEK.PTC.REJECT.PRODUCT.UPDATES.** CLASS(XFACILIT) –
ID(RDZADMIN) ACCESS(READ)
# activate changes
SETROPTS RACLIST(XFACILIT) REFRESH
# BANKING and INSURANCE have different configuration needs
config.enabled=SAF
# everyone receives product updates
product.enabled=TRUE
# only RDZADMIN can reject configuration updates
reject.config.updates=SAF
# only RDZADMIN can reject product updates
reject.product.updates=SAF
_RSE_FEK_SAF_CLASS=XFACILIT
Because there are no individualized product upgrade scenarios, the client administrator does not need to create or update the install/ and install/responsefiles/ subdirectories in /var/rdz/pushtoclient/grouping/<devgroup>/.
The client administrator must create the response files needed for product updates in the default-group directory, /var/rdz/pushtoclient/install/responsefiles/.
Assume that while the sample setup is active, a Developer for System z fix-pack with important fixes becomes available, but the timing of a banking project is such that various developers might be very weary of changing anything on their workstation right now.
To resolve the issue, the security administrator can grant all DEVBANK developers a grace period in which they can choose to postpone (reject) the update.
# start of grace period
PERMIT FEK.PTC.REJECT.PRODUCT.UPDATES.** CLASS(XFACILIT) –
ID(DEVBANK) ACCESS(READ)
# activate changes
SETROPTS RACLIST(FACILITY) REFRESH
# end of grace period
PERMIT FEK.PTC.REJECT.PRODUCT.UPDATES.** CLASS(XFACILIT) –
ID(DEVBANK) DELETE
# activate changes
SETROPTS RACLIST(FACILITY) REFRESH
z/OS Projects can be defined individually through the z/OS Projects perspective on the client, or z/OS Projects can be defined centrally on the host and propagated to the client on an individual user basis. These "host-based projects" look and function exactly like projects defined on the client except that their structure, members, and properties cannot be modified by the client, and they are only accessible when connected to the host.
The base directory for host-based projects is defined (by the client administrator) in /var/rdz/pushtoclient/keymapping.xml, and is /var/rdz/pushtoclient/projects by default.
Host-based projects are also eligible to participate in the multiple group setup discussed in Multiple developer groups. This eligibility means that host-based projects can be defined also in /var/rdz/pushtoclient/grouping/<devgroup>/projects/.
When a workspace is bound to a specific group, and there are project definitions for a user in this group and in the default group, the user receives the project definitions from both the default and the specific group.
Developer for System z addresses these issues by allowing CICS administrators to control CICS resource definition defaults, and to control the display properties of a CICS resource definition parameter by means of the CICS Resource Definition (CRD) server, which is part of Application Deployment Manager.
For example, the CICS administrator can supply certain CICS resource definition parameters that might not be updated by the application developer. Other CICS resource definition parameters may be updatable, with or without supplied defaults, or the CICS resource definition parameter can be hidden to avoid unnecessary complexity.
Once the application developer is satisfied with the CICS resource definitions they may be installed immediately in the running CICS test environment, or the definitions may be exported in a manifest for further editing and approval by a CICS administrator. The CICS administrator can use the administrative utility (batch utility) or the Manifest Processing tool to implement resource definition changes.
Refer to "(Optional) Application Deployment Manager" in the Host Configuration Guide (SC23-7658) for more information on the tasks needed to set up Application Deployment Manager on your host system.
The Application Deployment Manager CICS Resource Definition (CRD) server consists of the CRD server itself, a CRD repository, associated CICS resource definitions, and, when using the Web Service interface, Web Service bind files, and a sample pipeline message handler. The CRD server must run in a Web Owning Region (WOR), which is referenced in the Developer for System z documentation as the CICS primary connection region.
Refer to the Developer for System z Information Center (http://www-01.ibm.com/support/knowledgecenter/SSQ2R2_9.1.0/com.ibm.etools.getstart.wsentdev.doc/kc_version_welcome_rdz.html) to learn more about the services Application Deployment Manager available in the current release of Developer for System z.
CICS Transaction Server provides in version 4.1 and higher support for an HTTP interface designed using Representational State Transfer (RESTful) principles. This RESTful interface is now the strategic CICSTS interface for use by client applications. The older Web Service interface has been stabilized, and enhancements will be for the RESTful interface only.
Application Deployment Manager follows this statement of direction and requires the RESTful CRD server for all services that are new to Developer for System version 7.6 or higher.
The RESTful and Web Service interfaces can be active concurrently in a single CICS region, if desired. In this case, there will be two CRD servers active in the region. Both servers will share the same CRD repository. Note that CICS will issue some warnings about duplicate definitions when the second interface is defined to the region.
A CICS test environment may consist of several Multi-Region Option (MRO) connected regions. Over time, unofficial designations have been used to categorize these regions. Typical designations are Terminal Owning Region (TOR), Web Owning Region (WOR), Application Owning Region (AOR), and Data Owning Region (DOR).
A Web Owning Region is used to implement CICS Web Services support, and the Application Deployment Manager CICS Resource Definition (CRD) server must run in this region. This region is known to Application Deployment Manager as the CICS primary connection region. The CRD client implements a Web service connection to the CICS primary connection region.
CICS non-primary connection regions are all other regions that the CRD server can service. This service includes viewing resources using IBM CICS Explorer and defining resources using the CICS resource definition editor.
If CICSPlex® SM Business Application Services (BAS) is used to manage the CICS resource definitions of the CICS primary connection region, then all other CICS regions managed by BAS can be serviced by the CRD server.
CICS regions not managed by BAS require additional changes to be serviceable by the CRD server.
Actions done by the CRD server against the CICS resources are logged in the CICS CSDL TD queue, which typically points to DD MSGUSR of your CICS region.
If CICSPlex SM Business Application Services (BAS) is used to manage your CICS resource definitions, then the CICSPlex SM EYUPARM directive BASLOGMSG must be set to (YES) for the logging to be created.
The CRD server repository VSAM data set holds all the default resource definitions and must therefore be protected against updates, but developers must be allowed to read the values stored here. Refer to Define the data set profiles for sample RACF commands to protect the CRD repository.
When a SOAP message is received by CICS through the Web Service interface, the message is processed by a pipeline. A pipeline is a set of message handlers that are executed in sequence. CICS reads the pipeline configuration file to determine which message handlers should be invoked in the pipeline. A message handler is a program in which you can perform special processing of Web service requests and responses.
Application Deployment Manager provides a sample pipeline configuration file that specifies the invocation of a message handler and a SOAP header processing program.
The pipeline message handler (ADNTMSGH) is used for security by processing the user ID and password in the SOAP header. ADNTMSGH is referenced by the sample pipeline configuration file and must therefore be placed into the CICS RPL concatenation.
CPIH is the default transaction ID under which an application invoked by a pipeline will run. Typically, CPIH is set for a minimal level of authorization.
Developer for System z supplies multiple transactions that are used by the CRD server when defining and inquiring CICS resources. These transaction IDs are set by the CRD server, depending on the requested operation. Refer to "(Optional) Application Deployment Manager" in the Host Configuration Guide (SC23-7658) for more information on customizing the transaction IDs.
Transaction | Description |
---|---|
ADMS | For requests from the Manifest Processing tool to change CICS resources. Typically, this is intended for CICS administrators. This transaction requires a high level or authorization. |
ADMI | For requests that define, install or uninstall CICS resources. This transaction might require a medium level of authorization, depending on your site policies. |
ADMR | For all other requests that retrieve CICS environmental or resource information. This transaction might require a minimal level of authorization, depending on your site policies. |
Some, or all, of the resource definition requests done by the CRD server transactions should be secured. At a minimum, the update commands (update default Web service parameters, default descriptor parameters, and file name to data set name binding) should be secured to prevent all but CICS administrators from issuing these commands used to set global resource defaults.
When the transaction is attached, CICS resource security checking, if enabled, insures that the user ID is authorized to run the transaction ID.
Resource checking is controlled by the RESSEC option in the transaction that is running, the RESSEC system initialization parameter, and for the CRD server, the XPCT system initialization parameter.
Resource checking occurs only if the XPCT system initialization parameter has a value other than NO and either the RESSEC option in the TRANSACTION definition is YES or the RESSEC system initialization parameter is ALWAYS.
RALTER GCICSTRN SYSADM UACC(NONE) ADDMEM(ADMS)
PERMIT SYSADM CLASS(GCICSTRN) ID(#cicsadmin)
RALTER GCICSTRN DEVELOPER UACC(NONE) ADDMEM(ADMI)
PERMIT DEVELOPER CLASS(GCICSTRN) ID(#cicsdeveloper)
RALTER GCICSTRN ALLUSER UACC(READ) ADDMEM(ADMR)
SETROPTS RACLIST(TCICSTRN) REFRESH
SSL encryption of the data stream is supported when the Application Deployment Manager client uses the Web Services interface to invoke the CRD server. The usage of SSL for this communication is controlled by the SSL(YES) keyword in the CICSTS TCPIPSERVICE definition, as documented in RACF Security Guide for CICSTS.
CICSTS provides the ability to protect resources and the commands to manipulate them. Certain Application Deployment Manager actions might fail if security is active, but not configured completely (for example, granting permissions to manipulate new resource types).
Upon function failure in Application Deployment Manager, examine the CICS log for messages like the following, and take corrective action, as documented in RACF Security Guide for CICSTS.
DFHXS1111 %date %time %applid %tranid Security violation by user
%userid at netname %portname for resource %resource in class
%classname. SAF codes are (X'safresp',X'safreas'). ESM codes are
(X'esmresp',X'esmreas').
Developer for System z provides the administrative utility to let CICS administrators provide the default values for CICS resource definitions. These defaults can be read-only, or can be editable by the application developer.
The administrative utility is invoked by sample job ADNJSPAU in data set FEK.#CUST.JCL. The usage of this utility requires UPDATE access to the CRD repository.
ADNJSPAU is located in FEK.#CUST.JCL, unless the z/OS system programmer specified a different location when he customized and submitted job FEK.SFEKSAMP(FEKSETUP). See "Customization setup" in the Host Configuration Guide (SC23-7658) for more details.
UPDATE | Attributes following this keyword will be updatable by an application developer using Developer for System z. This is also the default for omitted attributes. |
PROTECT | Attributes following this keyword will display, but be protected from update by an application developer using Developer for System z. |
HIDDEN | Attributes following this keyword will not display, and will be protected from update by an application developer using Developer for System z. |
See the following ADNJSPAU code sample.
//ADNJSPAU JOB <JOB PARAMETERS>
//*
//ADNSPAU EXEC PGM=ADNSPAU,REGION=1M
//STEPLIB DD DISP=SHR,DSN=FEK.SFEKLOAD
//ADMREP DD DISP=OLD,DSN=FEK.#CUST.ADNREPF0
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
*
* CICSPlex SM parameters
*
DEFINE CPSMNAME( )
*DEFINE STAGINGGROUPNAME(ADMSTAGE)
*
* Manifest export rule
*
DEFINE MANIFESTEXPORTRULE(installOnly)
*
* CICS resource definition defaults
* Omitted attributes default to UPDATE.
*
* DB2TRAN default attributes
*
DEFINE DB2TRAN()
UPDATE DESCRIPTION()
ENTRY()
TRANSID()
*
* DOCTEMPLATE default attributes
*
DEFINE DOCTEMPLATE()
UPDATE DESCRIPTION()
TEMPLATENAME()
FILE() TSQUEUE() TDQUEUE() PROGRAM() EXITPGM()
DDNAME(DFHHTML) MEMBERNAME()
HFSFILE()
APPENDCRLF(YES) TYPE(EBCDIC)
*
* File default attributes
*
DEFINE FILE()
UPDATE DESCRIPTION()
RECORDSIZE() KEYLENGTH()
RECORDFORMAT(V) ADD(NO)
BROWSE(NO) DELETE(NO) READ(YES) UPDATE(NO)
REMOTESYSTEM() REMOTENAME()
PROTECT DSNAME() RLSACCESS(NO) LSRPOOLID(1) STRINGS(1)
STATUS(ENABLED) OPENTIME(FIRSTREF)
DISPOSITION(SHARE) DATABUFFERS(2) INDEXBUFFERS(1)
TABLE(NO) MAXNUMRECS(NOLIMIT)
READINTEG(UNCOMMITTED) DSNSHARING(ALLREQS)
UPDATEMODEL(LOCKING) LOAD(NO)
JNLREAD(NONE) JOURNAL(NO)
JNLSYNCREAD(NO) JNLUPDATE(NO)
JNLADD(NONE) JNLSYNCWRITE(YES)
RECOVERY(NONE) FWDRECOVLOG(NO)
BACKUPTYPE(STATIC)
PASSWORD() NSRGROUP()
CFDTPOOL() TABLENAME()
*
* Mapset default attributes
*
DEFINE MAPSET()
UPDATE DESCRIPTION()
PROTECT RESIDENT(NO) STATUS(ENABLED)
USAGE(NORMAL) USELPACOPY(NO)
** Processtype default attributes
*
DEFINE PROCESSTYPE()
UPDATE DESCRIPTION()
FILE(BTS)
PROTECT STATUS(ENABLED)
AUDITLOG() AUDITLEVEL(OFF)
*
* Program default attributes
*
DEFINE PROGRAM()
UPDATE DESCRIPTION()
CEDF(YES) LANGUAGE(LE370)
REMOTESYSTEM() REMOTENAME() TRANSID()
PROTECT API(CICSAPI) CONCURRENCY(QUASIRENT)
DATALOCATION(ANY) DYNAMIC(NO)
EXECKEY(USER) EXECUTIONSET(FULLAPI)
RELOAD(NO) RESIDENT(NO)
STATUS(ENABLED) USAGE(NORMAL) USELPACOPY(NO)
HIDDEN JVM(NO) JVMCLASS() JVMPROFILE(DFHJVMPR)
*
* TDQueue default attributes
*
DEFINE TDQUEUE()
UPDATE DESCRIPTION()
TYPE(INTRA)
* Extra partition parameters
DDNAME() DSNAME()
REMOTENAME() REMOTESYSTEM() REMOTELENGTH(1)
RECORDSIZE() BLOCKSIZE(0) RECORDFORMAT(UNDEFINED)
BLOCKFORMAT() PRINTCONTROL() DISPOSITION(SHR)
* Intra partition parameters
FACILITYID() TRANSID() TRIGERRLEVEL(1)
USERID()
* Indirect parameters
INDIRECTNAME()
PROTECT WAIT(YES) WAITACTION(REJECT)
* Extra partition parameters
DATABUFFERS(1)
SYSOUTCLASS() ERROROPTION(IGNORE)
OPENTIME(INITIAL) REWIND(LEAVE) TYPEFILE(INPUT)
* Intra partition parameters
ATIFACILITY(TERMINAL) RECOVSTATUS(NO)
*
* Transaction default attributes
*
DEFINE TRANSACTION()
UPDATE DESCRIPTION()
PROGRAM()
TWASIZE(0)
REMOTESYSTEM() REMOTENAME() LOCALQ(NO)
PROTECT PARTITIONSET() PROFILE(DFHCICST)
DYNAMIC(NO) ROUTABLE(NO)
ISOLATE(YES) STATUS(ENABLED)
RUNAWAY(SYSTEM) STORAGECLEAR(NO)
SHUTDOWN(DISABLED)
TASKDATAKEY(USER) TASKDATALOC(ANY)
BREXIT() PRIORITY(1) TRANCLASS(DFHTCL00)
DTIMOUT(NO) RESTART(NO) SPURGE(NO) TPURGE(NO)
DUMP(YES) TRACE(YES) CONFDATA(NO)
OTSTIMEOUT(NO) WAIT(YES) WAITTIME(00,00,00)
ACTION(BACKOUT) INDOUBT(BACKOUT)
RESSEC(NO) CMDSEC(NO)
TRPROF()
ALIAS() TASKREQ()
XTRANID() TPNAME() XTPNAME()
*
* URDIMAP attributes
*
DEFINE URIMAP()
UPDATE USAGE(CLIENT)
DESCRIPTION()
PATH(/required/path)
TCPIPSERVICE()
TRANSACTION()
PROGRAM()
PROTECT ANALYZER(NOANALYZER)
ATOMSERVICE()
CERTIFICATE()
CHARACTERSET()
CIPHERS()
CONVERTER()
HFSFILE()
HOST(host.mycompany.com)
HOSTCODEPAGE()
LOCATION()
MEDIATYPE()
PIPELINE()
PORT(NO)
REDIRECTTYPE(NONE)
SCHEME(HTTP)
STATUS(ENABLED)
TEMPLATENAME()
USERID()
WEBSERVICE()
*
* Optional file name to VSAM data set name binding
*
*DEFINE DSBINDING() DSNAME()
/*
Developer for System z version 7.6.1 added URIMAP support to the Administrative utility. To be able to use the URIMAP support, the CRD repository VSAM data set must be allocated with a maximum record size of 3000. Up till Developer for System z version 7.6.1, the sample CRD repository allocation job uses a maximum record size of 2000.
The following messages are issued by the Administrative utility to the SYSPRINT DD. Messages CRAZ1803E, CRAZ1891E, CRAZ1892E, and CRAZ1893E contain file status, VSAM return, VSAM function, and VSAM feedback codes. VSAM return, function, and feedback codes are documented in DFSMS Macro Instructions for Data Sets (SC26-7408). File status codes are documented in Enterprise COBOL for z/OS Language Reference (SC27-1408).
Explanation: The system programmer administrative utility completed successfully.
User response: None.
Explanation: The system programmer administrative utility completed with one or more warnings found when processing control statements.
User response: Check other warning messages.
Explanation: The system programmer administrative utility encountered a severe error.
User response: Check other warning messages.
Explanation: The system programmer administrative utility encountered a severe error opening the CRD repository.
User response: Check VSAM status, return, function, and feedback codes.
Explanation: The system programmer administrative utility encountered an unrecognized input control statement.
User response: Check a DEFINE command was followed by a single space, followed by the keyword CPSMNAME, STAGINGGROUPNAME, MANIFESTEXPORTRULE, DSBINDING, DB2TRAN, DOCTEMPLATE, FILE, MAPSET, PROCESSTYPE, PROGRAM, TDQUEUE, or TRANSACTION.
Explanation: The system programmer administrative utility is processing the DEFINE keyword input control statement.
User response: None.
Explanation: The system programmer administrative utility encountered an invalid manifest export rule.
User response: Check that the MANIFESTEXPORTRULE keyword value is "installOnly", "exportOnly", or "both".
Explanation: The system programmer administrative utility was processing a DEFINE DSBINDING control statement which is missing the DSNAME keyword.
User response: Check that the DEFINE DSBINDING control statement contains the DSNAME keyword.
Explanation: The system programmer administrative utility was processing a DEFINE control statement and encountered an invalid value for the named keyword.
User response: Check that the length and value of the named keyword is correct.
Explanation: The system programmer administrative utility was processing a DEFINE control statement and encountered a syntax error for a keyword or keyword value.
User response: Check that the keyword value is enclosed in parenthesis and immediately follows the keyword. The keyword and keyword value must both be contained on the same line.
Explanation: The system programmer administrative utility encountered a duplicate key error writing to the CRD repository.
User response: Check VSAM status, return, function, and feedback codes.
Explanation: The system programmer administrative utility encountered a severe error writing to the CRD repository.
User response: Check VSAM status, return, function, and feedback codes.
Explanation: The system programmer administrative utility encountered a severe error reading from the CRD repository.
User response: Check VSAM status, return, function, and feedback codes.
Define the debugger to a CICS region, as documented in the AQECSD sample CSD update job. AQECSD is located in FEK.#CUST.JCL, unless the z/OS system programmer specified a different location when the customized and submitted job FEK.SFEKSAMP(FEKSETUP). See "Customization setup" in the Host Configuration Guide (SC23-7658) for more details.
This chapter assists you with enhancing Developer for System z by writing exit routines.
Developer for System z provides exit points for select Developer for System z events. An exit point is a specific point in a function’s processing where the function invokes an exit routine if one exists. You can write an exit routine to perform additional processing.
Note that unlike most traditional exit points, Developer for System z exit points do not allow you to change the behavior of the function. The exit routine, if one exists, is invoked asynchronously, after the function completes. Developer for System z processing does not wait for the exit routine to end, nor does it check the completion status.
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -D<exit_point>.action=<user_exit>"
#_RSE_JAVAOPTS="$_RSE_JAVAOPTS -D<exit_point>.action.id=<userid>"
By default, the user ID assigned to RSE daemon is used to execute the provided exit routine. Uncomment and specify a user ID to use the specified ID for executing the user exit. There is no need to specify a password, because RSE will generate a PassTicket to be used as password when it switches to the specified user ID.
User exit routines are invoked as a z/OS UNIX shell command with possibly one or more arguments. This implies that the exit routine you develop must be executable from the z/OS UNIX command line. Common coding techniques include z/OS UNIX shell script and z/OS UNIX REXX exec, but compiled code like C/C++ is also possible.
See UNIX System Services User's Guide (SA22-7801) to learn more about z/OS UNIX shell scripts. See Using REXX and z/OS UNIX System Services (SA22-7806) to learn more about z/OS UNIX-specific extensions to the REXX language.
$ chmod 755 process_logon.sh
$ ls -l process_logon.sh
-rwxr-xr-x 1 IBMUSER SYS1 2228 Feb 28 23:44 process_logon.sh
Definitions in rsed.envvars are available to the user exit routine as environment variables.
RSE invokes the user exit routine with a single argument string. The argument string can be a single value or a single string which holds multiple blank delimited keywords and values. See Available exit points for more details.
Developer for System z uses console message ID FEK910I to display data related to user exits.
FEK910I <EXIT_POINT> EXIT: invoking <exit_point> processing exit
in thread <thread_id>
FEK910I <EXIT_POINT> EXIT: <message>
FEK910I <EXIT_POINT> EXIT: completed <exit_point> processing exit
in thread <thread_id>
Developer for System z allows you to run an exit routine with either the started task user ID or a specified user ID. However, you might want to execute some actions in the exit routine using another user ID, such as the client user ID in the logon exit routine. This can be accomplished using standard z/OS UNIX services, as shown in the following samples.
#! /bin/sh
myID=ibmuser
echo a $(id)
echo 'echo b $(id)' | su -s $myID
echo "echo c \$(id)" | su -s $myID
cat /u/ibmuser/iefbr14
echo "submit /u/ibmuser/iefbr14" | su -s $myID
This sample logon exit, executed by the started task user ID, will result in the following console messages:
+FEK910I LOGON EXIT: invoking logon processing exit in thread 411
+FEK910I LOGON EXIT: a uid=8(STCRSE) gid=1(STCGROUP)
+FEK910I LOGON EXIT: b uid=1(IBMUSER) gid=0(SYS1)
+FEK910I LOGON EXIT: c uid=1(IBMUSER) gid=0(SYS1)
+FEK910I LOGON EXIT: //IEFBR14 JOB CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1)
+FEK910I LOGON EXIT: //IEFBR14 EXEC PGM=IEFBR14
$HASP100 IEFBR14 ON INTRDR FROM STC03919
IBMUSER
IRR010I USERID IBMUSER IS ASSIGNED TO THIS JOB.
+FEK910I LOGON EXIT: JOB JOB03926 submitted from path '/u/ibmuser/iefbr14'
ICH70001I IBMUSER LAST ACCESS AT 00:46:13 ON MONDAY, MARCH 19, 2012
$HASP373 IEFBR14 STARTED - INIT 2 - CLASS A - SYS CD08
IEF403I IEFBR14 - STARTED - TIME=00.46.14
+FEK910I LOGON EXIT: completed logon processing exit in thread 411
IEFBR14 IEFBR14 IEFBR14 0000
IEF404I IEFBR14 - ENDED - TIME=00.46.14
$HASP395 IEFBR14 ENDED
$HASP309 INIT 2 INACTIVE ******** C=BA
/* rexx */
myID='ibmuser'
say userid()
address SYSCALL 'getpwnam' myID 'pw.'
say pw.1 pw.2 pw.3 pw.4 pw.5
address SYSCALL 'seteuid' pw.2 /* PW_UID = 2 */
say retval errno errnojr
say userid()
This sample logon exit, executed by the started task user ID, will result in the following console messages:
+FEK910I LOGON EXIT: invoking logon processing exit in thread 515
+FEK910I LOGON EXIT: STCRSE
+FEK910I LOGON EXIT: IBMUSER 1 0 / /bin/sh
+FEK910I LOGON EXIT: 0 0 0
+FEK910I LOGON EXIT: IBMUSER
+FEK910I LOGON EXIT: completed logon processing exit in thread 515
The audit user exit is invoked when the active audit log file is closed. (Auditing continues as RSE switched to a new audit log file.)
/usr/lpp/rdz/samples/process_audit.rex
This sample z/OS UNIX REXX exec builds a batch job that will process the audit log that was closed.
The logon user exit is invoked when a user has completed the logon process.
/usr/lpp/rdz/samples/process_logon.sh
This sample z/OS UNIX shell script writes a logon message to the console.
This chapter is provided to assist you with mimicking a TSO logon procedure by adding DD statements and data sets to the TSO environment in Developer for System z.
The TSO Commands service is the Developer for System z component which executes TSO and (batch) ISPF commands, and returns the result to the requesting client. These commands can be requested implicitly by the product, or explicitly by the user.
The sample members provided with Developer for System z create a minimal TSO/ISPF environment. If the developers in your shop need access to custom or third-party libraries, the z/OS system programmer must add the necessary DD statements and libraries to the TSO Commands service environment. Although the implementation is different in Developer for System z, the logic behind it is identical to the TSO logon procedure.
The ISPF.conf configuration file (by default located in /etc/rdz/) defines the TSO/ISPF environment used by Developer for System z. There is only one active ISPF.conf configuration file, which is used by all Developer for System z users.
sysproc=ISP.SISPCLIB,FEK.SFEKPROC
ispmlib=ISP.SISPMENU
isptlib=ISP.SISPTENU
ispplib=ISP.SISPPENU
ispslib=ISP.SISPSLIB
ispllib=ISP.SISPLOAD
myDD=HLQ1.LLQ1,HLQ2.LLQ2
#_RSE_ISPF_OPTS="$_RSE_ISPF_OPTS&ISPPROF=&SYSUID..ISPPROF"
Uncomment the statement (remove the leading pound sign (#) character) and provide the fully qualified data set name of the existing ISPF profile to use this facility.
*allocjob = ISP.SISPSAMP(ISPZISP2)
Although ISPF.conf only supports calling one allocation exec, there are no limits on that exec calling another exec. And the user ID of the client being passed as parameter opens the door to calling personalized allocation execs. You can, for example, check if member USERID’.EXEC(ALLOC)’ exists and execute it.
If the allocation exec scenarios described in the previous sections cannot handle your specific needs, you can create different instances of Developer for System z's RSE communication server, with each instance using its own ISPF.conf file. The main drawback of the method described below is that Developer for System z users must connect to different servers on the same host to get the desired TSO environment.
$ cd /etc/rdz
$ mkdir /etc/rdz/tso2
$ cp rsed.envvars /etc/rdz/tso2
$ cp ISPF.conf /etc/rdz/tso2
$ ls /etc/rdz/tso2
ISPF.conf rsed.envvars
$ oedit /etc/rdz/tso2/rsed.envvars
-> change: _RSE_RSED_PORT=4037
-> change: CGI_ISPCONF=/etc/rdz/tso2
-> change: -Ddaemon.log=/var/rdz/logs/tso2
-> change: -Duser.log=/var/rdz/logs/tso2
-> add at the END:
# -- NEEDED TO FIND THE REMAINING CONFIGURATION FILES
CFG_BASE=/etc/rdz
CLASSPATH=.:$CFG_BASE:$CLASSPATH
# --
$ oedit /etc/rdz/tso2/ISPF.conf
-> change: change as needed
The commands in the previous example copy the Developer for System z configuration files that require changes to a newly created tso2 directory. The CGI_ISPCONF variable in rsed.envvars must be updated to define the new ISPF.conf home directory , and daemon.log and user.log must be updated to define a new log location (which is created automatically if it does not exist). The _RSE_RSED_PORT update ensures that both the existing and the new RSE daemon will use unique port numbers. The CLASSPATH update ensures that RSE can find the configuration files that were not copied to tso2. The ISPF.conf file itself can be updated to match your needs. Note that the ISPF workarea (variable CGI_ISPWORK in rsed.envvars) can be shared among both instances.
What is left now is creating a new started task for RSE that uses a new port number and the new /etc/rdz/tso2 configuration files. Note that if _RSE_RSED_PORT is not changed in rsed.envvars, the new started task must specify a new port as startup argument.
Refer to the IBM Rational Developer for System z Host Configuration Guide (SC23-7658) for more information on the actions shown previously in this section.
There are times that you want multiple instances of Developer for System z active on the same system, for example, when testing an upgrade. However, some resources such as TCP/IP ports cannot be shared, so the defaults are not always applicable. Use the information in this section to plan the coexistence of the different instances of Developer for System z, after which you can use this configuration guide to customize them.
Although it is possible to share certain parts of Developer for System z between two (or more) instances, it is advised NOT to do so, unless their software levels are identical and the only changes are in configuration members. Developer for System z leaves enough customization room to make multiple instances that do not overlap and we strongly advise you to use these features.
In a limited set of circumstances, you can share all but (some of) the customizable parts. An example is providing non-SSL access for on-site usage, and SSL encoded communication for off-site usage.
Attention: The shared setup CANNOT
be used safely to test maintenance, a technical preview, or a new
release.
|
To set up another instance of an active Developer for System z installation, redo the customization steps for the parts that are different, using different data sets, directories, and ports to avoid overlapping the current setup.
In the SSL sample mentioned previously, the current RSE daemon setup can be cloned, after which the cloned setup can be updated. Next the RSE daemon startup JCL can be cloned and customized with a new TCP/IP port and the location of the updated configuration files. The MVS customizations (JES Job Monitor, and so on) can be shared between the SSL and non-SSL instances. This would result in the following actions:
$ cd /etc/rdz
$ mkdir /etc/rdz/ssl
$ cp rsed.envvars /etc/rdz/ssl
$ cp ssl.properties /etc/rdz/ssl
$ ls /etc/rdz/ssl/
rsed.envvars ssl.properties
$ oedit /etc/rdz/ssl/rsed.envvars
-> change: _RSE_RSED_PORT=4047
-> change: -Ddaemon.log=/var/rdz/logs/ssl
-> change: -Duser.log=/var/rdz/logs/ssl
-> add at the END:
# -- NEEDED TO FIND THE REMAINING CONFIGURATION FILES
CFG_BASE=/etc/rdz
CLASSPATH=.:$CFG_BASE:$CLASSPATH
# --
$ oedit /etc/rdz/ssl/ssl.properties
-> change: change as needed
The commands in the preceding example copy the Developer for System z configuration files that require changes to a newly created ssl directory. The daemon.log and user.log variables in rsed.envvars must be updated to define a new log location (which is created automatically if it does not exist). The CLASSPATH update ensures that RSE can find the configuration files that were not copied to ssl. The ssl.properties file itself can be updated to match your needs.
What is left now is creating a new started task for RSE that uses a new port number and the new /etc/rdz/ssl configuration files.
Refer to the related sections in the IBM Rational Developer for System z Host Configuration Guide (SC23-7658) for more information on the actions shown previously in this section.
In the SSL sample mentioned previously, the changes between the non-SSL and SSL-enabled RSE daemon are minimal, which makes it possible to automate the process of keeping their rsed.envvars files synchronized. This simplifies service roll-out, because only one rsed.envvars file must be maintained.
The following example adds the RSED port number to the log directory names and updates the CLASSPATH so that clones will find the remaining configuration files. Then the example enhances the started task JCL of the SSL-enabled RSE daemon to clone the rsed.envvars of the non-SSL RSE daemon upon startup, updating the port number in the process. Since the port number is embedded in the log directory name, it is automatically different between both daemons.
$ oedit /etc/rdz/rsed.envvars
-> change: -Ddaemon.log=/var/rdz/logs/$RSE_RSED_PORT
-> change: -Duser.log=/var/rdz/logs/$RSE_RSED_PORT
-> add at the END:
# -- NEEDED BY CLONES TO FIND THE REMAINING CONFIGURATION FILES
CFG_BASE=/etc/rdz
CLASSPATH=.:$CFG_BASE:$CLASSPATH
# --
$ mkdir /etc/rdz/ssl
$ cp /etc/rdz/ssl.properties /etc/rdz/etc/rdz/ssl
$ oedit /etc/rdz/ssl/ssl.properties
-> change: change as needed
//*
//* RSE DAEMON - SSL
//*
//RSED PROC IVP=, * 'IVP' to do an IVP test
// HOME='/usr/lpp/rdz',
// CNFG='/etc/rdz/ssl'
//*
// SET SED='"/RSED_PORT/s/4035/4034/"'
// SET FILE='rsed.envvars'
//*
//* copy /etc/rdz/rsed.envvars to /etc/rdz/ssl/rsed.envvars
//* and alter RSED_PORT
//*
//CLONE EXEC PGM=BPXBATCH,REGION=0M,COND=(4,LT),
// PARM='SH cd &CNFG;sed &SED ../&FILE>&FILE'
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
//*
//* start RSED with the newly created rsed.envvars
//*
//RSED EXEC PGM=BPXBATSL,REGION=0M,TIME=NOLIMIT,COND=(4,LT),
// PARM='PGM &HOME./bin/rsed.sh &IVP -C&CNFG'
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
// PEND
//*
When code changes are involved (maintenance, technical previews, new release), or your changes are fairly complex, you should do another installation of Developer for System z. This section describes possible points of conflict between the different installations.
The following list is a brief overview of items that must or are strongly advised to be different between the instances of Developer for System z:
A more detailed overview is listed as follows:
The Developer for System z Messages and Codes (SC14-7497) publication documents messages and return codes generated by Developer for System z components. Developer for System z Answers to common host configuration and maintenance issues (SC14-7373) describes various problem scenarios and their resolution.
More information is available through the Support section of the Developer for System z Web site (http://www-03.ibm.com/software/products/us/en/developerforsystemz/) where you can find Technotes that bring you the latest information from our support team.
In the Library section of the Web site (http://www-01.ibm.com/support/docview.wss?uid=swg27038517) you can also find the latest version of the Developer for System z documentation, including whitepapers.
The Developer for System z Information Center (http://www-01.ibm.com/support/knowledgecenter/SSQ2R2_9.1.0/com.ibm.etools.getstart.wsentdev.doc/kc_version_welcome_rdz.html) documents the Developer for System z client, and how it interacts with the host (from a client's perspective).
Valuable information can also be found in the z/OS internet library, available at http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/.
https://www.ibm.com/developerworks/support/rational/rfe/
The RSED start task supports the MODIFY LOGS operator command to collect Developer for System z host logs and setup information. The collected data is placed in a z/OS UNIX file, $TMPDIR/feklogs.%sysname.%jobname, where $TMPDIR is the value of the TMPDIR directive in rsed.envvars (default /tmp), %sysname is your z/OS system name and %jobname is the name of the RSED started task.
By default, only the server logs are collected. Command options allow you to collect different logs:
USER | Collect log files for the specified user ID’s |
AUDIT | Collect audit logs |
NOSERVER | Do not collect server logs |
Developer for System z will query your security product for access permits to FEK.CMD.LOGS.** profiles to determine if the requestor is allowed to collect the specified logs. By default, the requestor is the RSED started task user ID, unless the OWNER option is specified. Only the requestor has access to the file holding the collected data.
To collect data before the RSED started task can start, Developer for System z provides a sample job, FEKLOGS, which gathers all z/OS UNIX log files as well as Developer for System z installation and configuration information.
Sample job FEKLOGS is located in FEK.#CUST.JCL, unless you specified a different location when you customized and submitted job FEK.SFEKSAMP(FEKSETUP). See "Customization setup" in the Host Configuration Guide (SC23-7658) for more details.
The customization of FEKLOGS is described within the JCL. The customization encompasses the provision of a few key variables.
Developer for System z creates log files that can assist you and IBM support center in identifying and solving problems. The following list is an overview of log files that can be created on your z/OS host system. Next to these product-specific logs, be sure to check the SYSLOG for any related messages.
MVS based logs can be located through the appropriate DD statement. z/OS UNIX based log files are located in the following directories:
User-specific log files are located in userlog/$LOGNAME/, where userlog is the combined value of the user.log and DSTORE_LOG_DIRECTORY directives in rsed.envvars, and $LOGNAME is the logon user ID (uppercase). If the user.log directive is commented out or not present, the home path of the user is used. The home path is defined in the OMVS security segment of the user ID. If the DSTORE_LOG_DIRECTORY directive is commented out or not present, then .eclipse/RSE/ is appended to the user.log value.
The RSE daemon and RSE thread pool specific log files are located in daemon-home/server, where daemon-home is the value of the daemon.log directive in rsed.envvars. If the daemon.log directive is commented out or not present, the home directory of the user ID assigned to the RSED started task is used. The home directory is defined in the OMVS security segment of the user ID.
IVP-specific log files (Installation Verification Program) are located in the directory referenced by TMPDIR, if this variable is defined in rsed.envvars. If the variable is not defined, the files are created in /tmp.The MODIFY LOGS operator command for the RSED started task also creates its output in this directory.
Trace logging and logging of normal operations. The default value in the sample JCL FEK.#CUST.PROCLIB(DBGMGR) is SYSOUT=*.
Logging of normal operations. The default value in the sample JCL FEK.#CUST.PROCLIB(JMON) is SYSOUT=*.
Trace logging. The default value in the sample JCL FEK.#CUST.PROCLIB(JMON) is SYSOUT=*. Tracing is activated with the –TV parameter, see JES Job Monitor tracing for more details.
The redirected data of stdout, Java standard output of RSE daemon. The default value in the sample JCL FEK.#CUST.PROCLIB(RSED) is SYSOUT=*.
The redirected data of stderr, Java standard error output of RSE daemon. The default value in the sample JCL FEK.#CUST.PROCLIB(RSED) is SYSOUT=*.
The RSE daemon and RSE thread pool specific log files are located in daemon-home, where daemon-home is the value of the daemon.log directive in rsed.envvars. If the daemon.log directive is commented out or not present, the home directory of the user ID assigned to the RSED started task is used. The home directory is defined in the OMVS security segment of the user ID.
There are several log files created by the components related to RSE. All are located in userlog/$LOGNAME/, where userlog is the combined value of the user.log and DSTORE_LOG_DIRECTORY directives in rsed.envvars, and $LOGNAME is the logon user ID (uppercase). If the user.log directive is commented out or not present, the home path of the user is used. The home path is defined in the OMVS security segment of the user ID. If the DSTORE_LOG_DIRECTORY directive is commented out or not present, then .eclipse/RSE/ is appended to the user.log value.
Communication logging of SCLM Developer Toolkit, where userlog is the combined value of the user.log and DSTORE_LOG_DIRECTORY directives in rsed.envvars, and $LOGNAME is the logon user ID (uppercase). If the user.log directive is commented out or not present, the home path of the user is used. The home path is defined in the OMVS security segment of the user ID. If the DSTORE_LOG_DIRECTORY directive is commented out or not present, then .eclipse/RSE/ is appended to the user.log value.
When opening a connection with CARMA, using the batch interface, FEK.#CUST.SYSPROC(CRASUBMT) will start a server job (with the user's user ID as owner) named CRAport, where port is the TCP/IP port used.
If DD statement CARMALOG is specified in the chosen CARMA startup method, CARMA logging is redirected to this DD statement in the server job, otherwise it goes to SYSPRINT.
The SYSPRINT DD of the server job holds the CARMA logging, if DD statement CARMALOG is not defined.
The SYSTSPRT DD of the server job holds the system (TSO) messages for the CARMA server startup.
Communication logging of CARMA, where userlog is the combined value of the user.log and DSTORE_LOG_DIRECTORY directives in rsed.envvars, and $LOGNAME is the logon user ID (uppercase). If the user.log directive is commented out or not present, the home path of the user is used. The home path is defined in the OMVS security segment of the user ID. If the DSTORE_LOG_DIRECTORY directive is commented out or not present, then .eclipse/RSE/ is appended to the user.log value.
The fekfivpc command (CARMA related IVP test) will create the fekfivpc.log file to document the communication between RSE and CARMA. The log will be created in the directory referenced by TMPDIR, if this variable is defined in rsed.envvars. If the variable is not defined, the file is created in /tmp.
Output of the fekfivpi -file command (TSO/ISPF Client Gateway related IVP test). The log will be created in the directory referenced by TMPDIR, if this variable is defined in rsed.envvars. If the variable is not defined, the file is created in /tmp.
Output of the fekfivps -file command (SCLMDT-related IVP test). The log will be created in the directory referenced by TMPDIR, if this variable is defined in rsed.envvars. If the variable is not defined, the file is created in /tmp.
The SYSTSPRT DD of the step invoking the code review procedure holds the messages of the front end that drives the code analysis process.
The WORKSPCE DD of the step invoking the code review procedure holds the Eclipse workspace log messages of the code analysis process.
The ERRMSGS DD of the step invoking the code review procedure holds the stderr output of the code analysis process.
The SYSTSPRT DD of the step invoking the code review procedure holds the messages of the front-end that drives the code analysis process.
The WORKSPCE DD of the step invoking the code review procedure holds the Eclipse workspace log messages of the code analysis process.
The ERRMSGS DD of the step invoking the code review procedure holds the stderr output of the code analysis process.
When a product abnormally terminates, a storage dump is created to assist in problem determination. The availability and location of these dumps depends heavily on site-specific settings. The dumps may not be created, or the dumps may be created in different locations than those mentioned in the following sections.
When the program is running in MVS, check the system dump files and check your JCL for the following DD statements (depending on the product):
Refer to MVS JCL Reference (SA22-7597) and Language Environment Debugging Guide (GA22-7560) for more information on these DD statements.
In z/OS UNIX, most Developer for System z dumps are controlled by the Java Virtual Machine (JVM).
The JVM creates a set of dump agents by default during its initialization (SYSTDUMP and JAVADUMP). You can override this set of dump agents using the JAVA_DUMP_OPTS environment variable and further override the set by the use of -Xdump on the command line. JVM command-line options are defined in the _RSE_JAVAOPTS directive of rsed.envvars. Do not change any of the dump settings unless directed by the IBM support center.
The dump is written to a sequential MVS data set, using a default name of the form %uid.JVM.TDUMP.%job.D%y%m%d.T%H%M%S, or as determined by the setting of the JAVA_DUMP_TDUMP_PATTERN environment variable.
Variable | Usage |
---|---|
%uid | User ID |
%job | Job name |
%y | Year (2 digits) |
%m | Month (2 digits) |
%d | Day (2 digits) |
%H | Hour (2 digits) |
%M | Minute (2 digits) |
%S | Second (2 digits) |
The dump is written to a z/OS UNIX file named CEEDUMP.yyyymmdd.hhmmss.pid, where yyyymmdd equals the current date, hhmmss the current time and pid the current process ID. The possible locations of this file are described in z/OS UNIX dump locations.
The dump is written to a z/OS UNIX file named HEAPDUMP.yyyymmdd.hhmmss.pid.TXT, where yyyymmdd equals the current date, hhmmss the current time and pid the current process ID. The possible locations of this file are described in z/OS UNIX dump locations.
Note that Developer for System z provides an operator command to trigger this dump. See the "Operator commands" chapter in the Host Configuration Guide (SC23-7658) for more details.
The dump is written to a z/OS UNIX file named JAVADUMP.yyyymmdd.hhmmss.pid.TXT, where yyyymmdd equals the current date, hhmmss the current time and pid the current process ID. The possible locations of this file are described in z/OS UNIX dump locations.
Note that Developer for System z provides an operator command to trigger this dump. See the "Operator commands" chapter in the Host Configuration Guide (SC23-7658) for more details.
Refer to Java Diagnostic Guide (SC34-6358) for more information on JVM dumps, and Language Environment Debugging Guide (GA22-7560) for LE-specific information.
The JVM checks each of the following locations for existence and write-permission, and stores the CEEDUMP, HEAPDUMP, and JAVADUMP files in the first one available. Note that you must have enough free disk space for the dump file to be written correctly.
Debug Manager tracing is controlled by the system operator, as described in"Operator commands" in the Host Configuration Guide (SC23-7658).
JES Job Monitor tracing is controlled by the system operator, as described in "Operator commands" in the Host Configuration Guide (SC23-7658).
There are several log files created by the components related to RSE. Most are located in userlog/$LOGNAME/, where userlog is the combined value of the user.log and DSTORE_LOG_DIRECTORY directives in rsed.envvars, and $LOGNAME is the logon user ID (uppercase). If the user.log directive is commented out or not present, the home path of the user is used. The home path is defined in the OMVS security segment of the user ID. If the DSTORE_LOG_DIRECTORY directive is commented out or not present, then .eclipse/RSE/ is appended to the user.log value.
The amount of data written to ffs*.log and rsecomm.log is controlled by the modify rsecommlog operator command, or by setting debug_level in rsecomm.properties. See "Operator commands" in the Host Configuration Guide (SC23-7658) and "(Optional) RSE tracing" in the Host Configuration Guide (SC23-7658) for more details.
The creation of the .dstore* log files is controlled by the –DDSTORE_* Java startup options, as described in "Defining extra Java startup parameters with _RSE_JAVAOPTS" in the Host Configuration Guide (SC23-7658).
The RSE daemon and RSE thread pool specific log files are located in daemon-home, where daemon-home is the value of the daemon.log directive in rsed.envvars. If the daemon.log directive is commented out or not present, the home directory of the user ID assigned to the RSED started task is used. The home directory is defined in the OMVS security segment of the user ID.
The amount of data written to rsedaemon.log and rseserver.log is controlled by the modify rsedaemonlog and modify rseserverlog operator commands or by setting debug_level in rsecomm.properties . See "Operator commands" in the Host Configuration Guide (SC23-7658) and "(Optional) RSE tracing" in the Host Configuration Guide (SC23-7658) for more details.
serverlogs.count, stderr.*.log, and stdout.*.log are only created if the enable.standard.log directive in rsed.envvars is active, or if the function is dynamically activated with the modify rsestandardlog on operator command..
The user can control the amount of trace info that a
CARMA server generates by setting Trace Level in the properties tab
of the CARMA connection on the client. The choices for Trace
Level are:
Error Logging
Refer to Log files for more information on log file locations.
The z/OS system programmer can control the amount of
trace info that CARMA’s CRASTART startup method generates by
setting crastart.syslog in CRASRV.properties,
and by setting the debug level for rsecomm.log in rsecomm.properties or
with an operator command.
//COBOL EXEC PGM=IGYCRCTL,REGION=2048K,
//* PARM=('EXIT(ADEXIT(ELAXMGUX))',
// PARM=('EXIT(ADEXIT(''MAXTRACE'',ELAXMGUX))',
// 'ADATA',
// 'LIB',
// 'TEST(NONE,SYM,SEP)',
// 'LIST',
// 'FLAG(I,I)'&CICS &DB2 &COMP)
ABOUT TOO OPEN SIDEFILE1 - NAME = 'uid.DT021207.TT110823.M0000045.C0000000'
SUCCESSFUL OPEN SIDEFILE1 - NAME = 'uid.DT021207.TT110823.M0000045.C0000000'
ABOUT TOO OPEN SIDEFILE2 - NAME = 'uid.DT021207.TT110823.M0000111.C0000001'
SUCCESSFUL OPEN SIDEFILE2 - NAME = 'uid.DT021207.TT110823.M0000111.C0000001'
ABOUT TOO OPEN SIDEFILE3 - NAME = 'uid.DT021207.TT110823.M0000174.C0000002'
SUCCESSFUL OPEN SIDEFILE3 - NAME = 'uid.DT021207.TT110823.M0000174.C0000002'
ABOUT TOO OPEN SIDEFILE4 - NAME = 'uid.DT021207.TT110823.M0000236.C0000003'
SUCCESSFUL OPEN SIDEFILE4 - NAME = 'uid.DT021207.TT110823.M0000236.C0000003'
22 //COBOL.WSEDSF1 DD DISP=MOD,
// DSN=uid.ERRCOB.member.SF.Z682746.XML
23 //COBOL.WSEDSF2 DD DISP=MOD,
// DSN=uid.ERRCOB.member.SF.Z682747.XML
Developer for System z requires that the z/OS UNIX file system and some z/OS UNIX files have certain permission bits set.
Remote Systems Explorer (RSE) is the Developer for System z component that provides core services such as connecting the client to the host. It must be allowed to perform tasks such as creating the user’s security environment.
Similar errors (such as messages BPXP014I and BPXP015I) can be expected if the file systems hosting Java or z/OS UNIX binaries are mounted with the NOSETUID parameter.
Use the TSO ISHELL command to list the current status of the SETUID bit. In the ISHELL panel, select File_systems > 1. Mount table... to list the mounted file systems. The a line command will show the attributes for the selected file system, where the “Ignore SETUID” field should be 0.
Remote Systems Explorer (RSE) is the Developer for System z component that provides core services such as connecting the client to the host. It must run program controlled in order to perform tasks such as switching to the user ID of the client.
The z/OS UNIX program control bit is set during SMP/E install where needed, except for the Java interface to your security product, as documented in Security considerations. This permission bit might get lost if you did not preserve it during a manual copy of the Developer for System z directories.
Use z/OS UNIX command ls –E to list the extended attributes, in which the program control bit is marked with the letter p, as shown in the following sample ($ is the z/OS UNIX prompt):
$ cd /usr/lpp/rdz
$ ls -E lib/fekf*
-rwxr-xr-x -ps- 2 user group 94208 Jul 8 12:31 lib/fekfdir.dll
$ cd /usr/lpp/rdz
$ su
# extattr +p lib/fekf*
# exit
$ ls -E lib/fekf*
-rwxr-xr-x -ps- 2 user group 94208 Jul 8 12:31 lib/fekfdir.dll
Remote Systems Explorer (RSE) is the Developer for System z component that provides core services such as connecting the client to the host. It must run APF-authorized in order to perform tasks such as displaying detailed process resource usage.
The z/OS UNIX APF bit is set during SMP/E install where needed. This permission bit might get lost if you did not preserve it during a manual copy of the Developer for System z directories.
Use z/OS UNIX command ls -E to list the extended attributes, in which the APF bit is marked with the letter a, as shown in the following sample ($ is the z/OS UNIX prompt):
$ cd /usr/lpp/rdz
$ ls -E bin/fekfrivp
-rwxr-xr-x aps- 2 user group 114688 Sep 17 06:41 bin/fekfrivp
Use z/OS UNIX command extattr +a to set the APF bit manually, as shown in the following sample ($ and # are the z/OS UNIX prompts):
$ cd /usr/lpp/rdz
$ su
# extattr +a bin/fekfrivp
# exit
$ ls -E bin/fekfrivp
-rwxr-xr-x aps- 2 user group 114688 Sep 17 06:41 bin/fekfrivp
Some of the optional Developer for System z services require that MVS load modules are available to z/OS UNIX. This is done by creating a stub (a dummy file) in z/OS UNIX with the "sticky" bit on. When the stub is executed, z/OS UNIX will look for an MVS load module with the same name and execute the load module instead.
The z/OS UNIX sticky bit is set during SMP/E install where needed. These permission bits might get lost if you did not preserve them during a manual copy of the Developer for System z directories.
$ cd /usr/lpp/rdz
$ ls -l bin/CRA*
-rwxr-xr-t 2 user group 71 Jul 8 12:31 bin/CRASTART
$ cd /usr/lpp/rdz
$ su
# chmod +t bin/CRA*
# exit
$ ls -l bin/CRA*
-rwxr-xr-t 2 user group 71 Jul 8 12:31 bin/CRASTART
With the netstat command (TSO or z/OS UNIX) you can get an overview of the ports currently in use. The output of this command will look similar to the following example. The ports used are the last number (behind the "..") in the "Local Socket" column. Since these ports are already in use, they cannot be used for the Developer for System z configuration.
MVS TCP/IP NETSTAT CS VxRy TCPIP Name: TCPIP 16:36:42
User Id Conn Local Socket Foreign Socket State
------- ---- ------------ -------------- -----
BPXOINIT 00000014 0.0.0.0..10007 0.0.0.0..0 Listen
INETD4 0000004D 0.0.0.0..512 0.0.0.0..0 Listen
RSED 0000004B 0.0.0.0..4035 0.0.0.0..0 Listen
JMON 00000038 0.0.0.0..6715 0.0.0.0..0 Listen
MVS TCP/IP NETSTAT CS VxRy TCPIP Name: TCPIP 12:46:25
User Id Conn State
------- ---- -----
BPXOINIT 00000018 Listen
Local Socket: 0.0.0.0..10007
Foreign Socket: 0.0.0.0..0
INETD4 00000046 Listen
Local Socket: 0.0.0.0..512
Foreign Socket: 0.0.0.0..0
RSED 0000004B Listen
Local Socket: 0.0.0.0..4035
Foreign Socket: 0.0.0.0..0
JMON 00000037 Listen
Local Socket: 0.0.0.0..6715
Foreign Socket: 0.0.0.0..0
Another limitation that can exist is reserved TCP/IP ports. There are the following two common places to reserve TCP/IP ports:
This is the data set referred to by the PROFILE DD statement of the TCP/IP started task, often named SYS1.TCPPARMS(TCPPROF).
Refer to Communications Server: IP Configuration Guide (SC31-8775) for more information on these statements.
These reserved ports can be listed with the netstat portl command (TSO or z/OS UNIX), which creates an output like that in the example as follows:
MVS TCP/IP NETSTAT CS VxRy TCPIP Name: TCPIP 17:08:32
Port# Prot User Flags Range IP Address
----- ---- ---- ----- ----- ----------
00007 TCP MISCSERV DA
00009 TCP MISCSERV DA
00019 TCP MISCSERV DA
00020 TCP OMVS D
00021 TCP FTPD1 DA
00025 TCP SMTP DA
00053 TCP NAMESRV DA
00080 TCP OMVS DA
03500 TCP OMVS DAR 03500-03519
03501 TCP OMVS DAR 03500-03519
Refer to Communications Server: IP System Administrator’s Commands (SC31-8781) for more information on the NETSTAT command.
The RSE daemon, which is a z/OS UNIX Java process, requires a large region size to perform its functions. Therefore it is important to set large storage limits for OMVS address spaces.
The RSE daemon is started by JCL using BPXBATSL, whose region size must be 0.
Set MAXASSIZE in SYS1.PARMLIB(BPXPRMxx), which defines the default OMVS address space (process) region size, to 2G. This is the maximum size allowed. This is a system-wide limit, and thus active for all z/OS UNIX address spaces. If this is not desired, then you can set the limit also just for Developer for System z in your security software.
Check ASSIZEMAX in the daemon’s user ID OMVS segment, and set it to 2147483647 or, preferably, to NONE to use the SYS1.PARMLIB(BPXPRMxx) value.
Make sure you are not allowing system exits IEFUSI or IEALIMIT to control OMVS address space region sizes. A possible way to accomplish this is by coding SUBSYS(OMVS,NOEXITS) in SYS1.PARMLIB(SMFPRMxx).
Keyword MEMLIMIT in SYS1.PARMLIB(SMFPRMxx) limits how much virtual storage a 64-bit task can allocate above the 2GB bar. Unlike the REGION parameter in JCL, MEMLIMIT=0M means that the process cannot use virtual storage above the bar.
If MEMLIMIT is not specified in SMFPRMxx, the default value is 0M, so tasks are bound to the (31-bit) 2GB below the bar. The default changed in z/OS 1.10 to 2G, allowing 64-bit tasks to use up to 4GB (the 2GB below the bar and the 2GB above the bar granted by MEMLIMIT).
MEMLIMIT can also be specified as parameter on an EXEC card in JCL. If no MEMLIMIT parameter is specified, the default is the value defined to SMF, except when REGION=0M is specified, in which case the default is NOLIMIT.
When a user selects error feedback during a compile action, several temporary data sets are created by Developer for System z. When one of these data sets runs out of space, the compile jobs ends with a B37-04 space abend.
Adjust the space allocation in FEK.SFEKPROC(FEKFERRF) when your users experience this problem. The default value is SPACE(200,40) TRACKS.
SYS1.PARMLIB(BPXPRMxx) defines many z/OS UNIX related limitations, which might be reached when several Developer for System z clients are active. Most BPXPRMxx values can be changed dynamically with the SETOMVS and SET OMVS console commands.
Use the SETOMVS LIMMSG=ALL console command to have z/OS UNIX display console messages (BPXI040I) when any of the BPXPRMxx limits is about to be reached.
This section is provided to assist you with some common problems that you may encounter when setting up Secure Socket Layer (SSL), or during checking or modifying an existing setup. This section also provides a sample setup to support users authenticating themselves with an X.509 certificate.
Secure communication means ensuring that your communication partner is who he claims to be, and transmitting information in a manner that makes it difficult for others to intercept and read the data. SSL provides this ability in a TCP/IP network. It works by using digital certificates to identify yourself and a public key protocol to encrypt the communication. Refer to Security Server RACF Security Administrator's Guide (SA22-7683) for more information on digital certificates and the public key protocol used by SSL.
The actions needed to set up SSL communications for Developer for System z will vary from site to site, depending on the exact needs, the RSE communication method used and what’s already available at the site.
In this section we will clone the current RSE definitions, so that we have a 2nd RSE daemon connection that will use SSL. We will also create our own security certificates to be used by the different parts of the RSE connection.
Some tasks described in the following sections expect you to be active in z/OS UNIX. This can be done by issuing the TSO command OMVS. Use the exit command to return to TSO.
The DSTORE_SSL_ALGORITHM variable in the _RSE_JAVAOPTS directive of rsed.envvars lets you choose between SSL and its successor TLS (Transport Layer Security) as encryption method, as documented in "Defining extra Java startup parameters with _RSE_JAVAOPTS" in the Host Configuration Guide (SC23-7658).
The identity certificates and the encryption/decryption keys used by SSL are stored in a key file. Different implementations of this key file exist, depending on the application type.
However, all implementations follow the same principle. A command generates a key pair (a public key and associated private key). The command then wraps the public key into an X.509 self-signed certificate, which is stored as a single-element certificate chain. This certificate chain and the private key are stored as an entry (identified by an alias) in a key file.
Certificate storage | Created and managed by | RSE daemon | RSE server |
---|---|---|---|
key ring | SAF-compliant security product | supported | supported |
key database | z/OS UNIX’s gskkyman | supported | / |
key store | Java’s keytool | / | supported |
STEPLIB=$STEPLIB:SYS1.SIEALNKE
Refer to Security Server RACF Security Administrator’s Guide (SA22-7683) for information on RACF and digital certificates. gskkyman documentation can be found in System SSL Programming (SC24-5901), and keytool documentation is available at http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html.
Do not execute this step if you use gskkyman to create the RSE daemon key database and keytool to create the RSE server key store.
The RACDCERT command installs and maintains private keys and certificates in RACF. RACF supports multiple private keys and certificates to be managed as a group. These groups are called key rings.
Certificates can be either self-signed or signed by a Certificate Authority (CA). A certificate signed by a CA means that the CA guarantees that the owner of the certificate is who he claims to be. The signing process adds the CA credentials (also a certificate) to your certificate, making it a multi-element certificate chain.
When using a certificate signed by a CA, you can avoid trust validation questions by the Developer for System z client, if the client already trusts the CA.
Refer to Security Server RACF Command Language Reference (SA22-7687) for details on the RACDCERT command.
# permit RSE daemon to access certificates
RDEFINE FACILITY IRR.DIGTCERT.LIST UACC(NONE)
RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)
PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ACCESS(READ) ID(stcrse)
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ACCESS(READ) ID(stcrse)
# refresh to make the changes visible
SETROPTS RACLIST(FACILITY) REFRESH
# create self-signed certificate
RACDCERT ID(stcrse) GENCERT SUBJECTSDN(CN('rdz rse ssl') +
OU('rdz') O('IBM') L('Raleigh') SP('NC') C('US')) +
NOTAFTER(DATE(2017-05-21)) WITHLABEL('rdzrse') KEYUSAGE(HANDSHAKE)
# (optional) additional steps required to use a signed certificate
# 1. create a signing request for the self-signed certificate
RACDCERT ID(stcrse) GENREQ (LABEL('rdzrse')) DSN(dsn)
# 2. send the signing request to your CA of choice
# 3. check if the CA credentials (also a certificate) are already known
RACDCERT CERTAUTH LIST
# 4. mark the CA certificate as trusted
RACDCERT CERTAUTH ALTER(LABEL('CA cert')) TRUST
# or add the CA certificate to the database
RACDCERT CERTAUTH ADD(dsn) WITHLABEL('CA cert') TRUST
# 5. add the signed certificate to the database;
# this will replace the self-signed one
RACDCERT ID(stcrse) ADD(dsn) WTIHLABEL('rdzrse') TRUST
# Do NOT delete the self-signed certificate before replacing it.
# If you do, you lose the private key that goes with the certificate,
# which makes the certificate useless.
RACDCERT ID(stcrse) ADDRING(rdzssl.racf)
RACDCERT ID(stcrse) CONNECT(LABEL('rdzrse') RING(rdzssl.racf) +
DEFAULT USAGE(PERSONAL))
# additional step required to use a signed certificate
# 6. add CA certificate to key ring
RACDCERT ID(stcrse) CONNECT(CERTAUTH LABEL('CA cert') +
RING(rdzssl.racf))
# refresh to make the changes visible
SETROPTS RACLIST(DIGTCERT) REFRESH
The preceding sample starts by creating the necessary profiles and permitting user ID STCRSE access to key rings and certificates owned by that user ID. The user ID used must match the user ID used to run the SSL RSE daemon. The next step is creating a new, self-signed, certificate with label rdzrse. No password is needed. This certificate is then added to a newly created key ring (rdzssl.racf). Just as with the certificate, no password is needed for the key ring. The steps required to use a signed certificate are also listed.
Note that the CA certificate used to sign your certificate can, in turn, also be signed by another, higher level, CA certificate. If that happens, the higher level CA certificate must also be added to the key ring. This process repeats until the higher level CA certificate is a root CA certificate, which is always a self-signed certificate.
The result can be verified with the following list and listring options:
RACDCERT ID(stcrse) LIST
Digital certificate information for user STCRSE:
Label: rdzrse
Certificate ID: 2QjW1OXi0sXZ1aaEqZmihUBA
Status: TRUST
Start Date: 2007/05/24 00:00:00
End Date: 2017/05/21 23:59:59
Serial Number:
>00<
Issuer's Name:
>CN=my CA.OU=rdz.O=IBM.L=Raleigh.SP=NC.C=US<
Subject's Name:
>CN=rdz rse ssl.OU=rdz.O=IBM.L=Raleigh.SP=NC.C=US<
Private Key Type: Non-ICSF
Private Key Size: 1024
Ring Associations:
Ring Owner: STCRSE
Ring:
>rdzssl.racf<
RACDCERT ID(stcrse) LISTRING(rdzssl.racf)
Digital ring information for user STCRSE:
Ring:
>rdzssl.racf<
Certificate Label Name Cert Owner USAGE DEFAULT
-------------------------------- ------------ -------- -------
rdzrse ID(STCRSE) PERSONAL YES
CA cert CERTAUTH CERTAUTH NO
In this step a new instance of the RSE configuration files is created, so that the SSL setup can run parallel with the existing one(s). The following sample commands expect the configuration files to be in /etc/rdz/, which is the default location used in "Customization setup" in the Host Configuration Guide (SC23-7658).
$ cd /etc/rdz
$ mkdir ssl
$ cp rsed.envvars ssl
$ cp ssl.properties ssl
$ ls ssl
rsed.envvars ssl.properties
The z/OS UNIX commands listed in the preceding example create a subdirectory called ssl and populate it with the configuration files that require changes. We can share the other configuration files, the installation directory, and the MVS components, because they are not SSL-specific.
By reusing most of the existing configuration files, we can focus on the changes that are actually required for setting up SSL and avoid doing the complete RSE setup again. (For example, we can avoid defining a new location for ISPF.conf.)
So far, the definitions are an exact copy of the current setup, which implies that the logs of the new RSE daemon will overlay the current server log files. RSE also needs to know where to find the configuration files that were not copied to the ssl directory. Both issues can be addressed by minor changes to rsed.envvars.
$ oedit /etc/rdz/ssl/rsed.envvars
-> change: _RSE_RSED_PORT=4047
-> change: -Ddaemon.log=/var/rdz/logs/ssl
-> change: -Duser.log=/var/rdz/logs/ssl
-> add at the END:
# -- NEEDED TO FIND THE REMAINING CONFIGURATION FILES
CFG_BASE=/etc/rdz
CLASSPATH=.:$CFG_BASE:$CLASSPATH
# --
The changes in the preceding example define a new log location (which will be created by RSE daemon if the log location does not exist). The changes also update the CLASSPATH so that the SSL RSE processes will first search the current directory (/etc/rdz/ssl) for configuration files and then search the original directory (/etc/rdz).
By updating ssl.properties, RSE is instructed to start using SSL encrypted communication.
$ oedit /etc/rdz/ssl/ssl.properties
-> change: enable_ssl=true
-> uncomment and change: daemon_keydb_file=rdzssl.racf
-> uncomment and change: daemon_key_label=rdzrse
-> uncomment and change: server_keystore_file=rdzssl.racf
-> uncomment and change: server_keystore_label=rdzrse
-> uncomment and change: server_keystore_type=JCERACFKS
The changes in the preceding example enable SSL and tell the RSE daemon and RSE server that their (shared) certificate is stored under label rdzrse in key ring rdzssl.racf. The JCERACFKS keyword tells RSE server that a SAF-compliant key ring is used as key store.
Note that System SSL (used by the daemon) always uses ICSF, the interface to System z cryptographic hardware, when available. To be able to share the daemon definitions with the server when using ICSF, server_keystore_type JCECCARACFKS must be specified. Here, a SAF-compliant key ring is also used as key store for the public keys, but the private key is stored in ICSF. As documented in Cryptographic Services ICSF Administrator's Guide (SA22-7521), ICSF uses profiles in the CSFKEYS and CSFSERV security classes to control who can use cryptographic keys and services.
//RSEDSSL JOB CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1),USER=STCRSE
//*
//* RSE DAEMON - SSL
//*
//RSED PROC TMPDIR=,
// PORT=,
// IVP=, * 'IVP' to do an IVP test
// CNFG='/etc/rdz/ssl',
// HOME='/usr/lpp/rdz'
//*
//RSED EXEC PGM=BPXBATSL,REGION=0M,TIME=NOLIMIT,
// PARM='PGM &HOME./bin/rsed.sh &IVP -C&CNFG -P&PORT -T&TMPDIR'
//STDOUT DD SYSOUT=*
//STDERR DD SYSOUT=*
// PEND
//*
//RSED EXEC RSED
//*
The SSL host configuration is complete and the RSE daemon for SSL can be started by submitting job FEK.#CUST.PROCLIB(RSEDSSL), which was created earlier.
The new setup can now be tested by connecting with the Developer for System z client. Since we created a new configuration for use by SSL (by cloning the existing one), a new connection must be defined on the client, using port 4047 for the RSE daemon.
Upon connection, the host and client will start with some handshaking in order to set up a secure path. Part of this handshaking is the exchange of certificates. If the Developer for System z client does not recognize the host certificate or the CA that signed it, Developer for System z client will prompt the user asking if this certificate can be trusted.
By clicking the Finish button the user can accept this certificate as trusted, after which the connection initialization continues.
Once a certificate is known to the client, this dialog is not shown again. The list of trusted certificates can be managed by selecting Window > Preferences... > Remote Systems > SSL, which shows the following dialog:
If SSL communication fails, the client will return an error message. More information is available in the different server and user log files, as described in RSE daemon and thread pool logging and RSE user logging.
RSE daemon supports users authenticating themselves with an X.509 certificate. Using SSL encrypted communication is a prerequisite for this function, because it is an extension to the host authentication with a certificate used in SSL.
There are multiple ways to do certificate authentication for a user, as described in Client authentication using X.509 certificates. The next steps document the setup needed to support the method where your security software authenticates the certificate using the HostIdMappings certificate extension.
RACDCERT CERTAUTH ALTER(LABEL('HighTrust CA')) HIGHTRUST
RACDCERT ID(stcrse) CONNECT(CERTAUTH LABEL('HighTrust CA') +
RING(rdzssl.racf))
This concludes the security software setup for the CA certificate.
RDEFINE SERVAUTH IRR.HOST.CDFMVS08.RALEIGH.IBM.COM UACC(NONE)
PERMIT IRR.HOST.CDFMVS08.RALEIGH.IBM.COM CLASS(SERVAUTH) +
ACCESS(READ) ID(stcrse)
SETROPTS CLASSACT(SERVAUTH) RACLIST(SERVAUTH)
or
SETROPTS RACLIST(SERVAUTH) REFRESH
This concludes the security software setup for the HostIdMappings extension.
Do not execute this step if you use an SAF-compliant key ring for the RSE daemon key database.
gskkyman is a z/OS UNIX shell-based, menu-driven, program that creates, populates, and manages a z/OS UNIX file that contains private keys, certificate requests, and certificates. This z/OS UNIX file is called a key database.
PATH=$PATH:/usr/lpp/gskssl/bin
export NLSPATH=/usr/lpp/gskssl/lib/nls/msg/En_US.IBM-1047/%N:$NLSPATH
export STEPLIB=$STEPLIB:SYS1.SIEALNKE
$ cd /etc/rdz/ssl
$ gskkyman Database Menu
1 - Create new database
Enter option number: 1
Enter key database name (press ENTER to return to menu): rdzssl.kdb
Enter database password (press ENTER to return to menu): rsessl
Re-enter database password: rsessl
Enter password expiration in days (press ENTER for no expiration):
Enter database record length (press ENTER to use 2500):
Key database /etc/rdz/ssl/rdzssl.kdb created.
Press ENTER to continue.
Key Management Menu
6 - Create a self-signed certificate
Enter option number (press ENTER to return to previous menu): 6
Certificate Type
5 - User or server certificate with 1024-bit RSA key
Select certificate type (press ENTER to return to menu): 5
Enter label (press ENTER to return to menu): rdzrse
Enter subject name for certificate
Common name (required): rdz rse ssl
Organizational unit (optional): rdz
Organization (required): IBM
City/Locality (optional): Raleigh
State/Province (optional): NC
Country/Region (2 characters - required): US
Enter number of days certificate will be valid (default 365): 3650
Enter 1 to specify subject alternate names or 0 to continue: 0
Please wait .....
Certificate created.
Press ENTER to continue.
Key Management Menu
0 - Exit program
Enter option number (press ENTER to return to previous menu): 0
$ ls -l rdzssl.*
total 152
-rw------- 1 IBMUSER SYS1 35080 May 24 14:24 rdzssl.kdb
-rw------- 1 IBMUSER SYS1 80 May 24 14:24 rdzssl.rdb
$ chmod 644 rdzssl.*
$ ls -l rdzssl.*
-rw-r--r-- 1 IBMUSER SYS1 35080 May 24 14:24 rdzssl.kdb
-rw-r--r-- 1 IBMUSER SYS1 80 May 24 14:24 rdzssl.rdb
The preceding sample starts by creating a key database called rdzssl.kdb with password rsessl. Once the database exists, it is populated by creating a new, self-signed, certificate, valid for about 10 years (not counting leap days). The certificate is stored under the label rdzrse and with the same password (rsessl) as the one used for the key database (this is an RSE requisite).
gskkyman allocates the key database with a (very secure) 600 permission bit mask (only owner has access). Unless the daemon uses the same user ID as the creator of the key database, permissions have to be set less restrictive. 644 (owner has read/write, everyone has read) is a usable mask for the chmod command.
The result can be verified by selecting the Show certificate information option in the Manage keys and certificates submenu, as follows:
$ gskkyman
Database Menu
2 - Open database
Enter option number: 2
Enter key database name (press ENTER to return to menu): rdzssl.kdb
Enter database password (press ENTER to return to menu): rsessl
Key Management Menu
1 - Manage keys and certificates
Enter option number (press ENTER to return to previous menu): 1
Key and Certificate List
1 - rdzrse
Enter label number (ENTER to return to selection menu, p for previous list): 1
Key and Certificate Menu
1 - Show certificate information
Enter option number (press ENTER to return to previous menu): 1
Certificate Information
Label: rdzrse
Record ID: 14
Issuer Record ID: 14
Trusted: Yes
Version: 3
Serial number: 45356379000ac997
Issuer name: rdz rse ssl
rdz
IBM
Raleigh
NC
US
Subject name: rdz rse ssl
rdz
IBM
Raleigh
NC
US
Effective date: 2007/05/24
Expiration date: 2017/05/21
Public key algorithm: rsaEncryption
Public key size: 1024
Signature algorithm: sha1WithRsaEncryption
Issuer unique ID: None
Subject unique ID: None
Number of extensions: 3
Enter 1 to display extensions, 0 to return to menu: 0
Key and Certificate Menu
0 - Exit program
Enter option number (press ENTER to return to previous menu): 0
The following ssl.properties sample shows that the daemon_* directives differ from the SAF key ring sample shown earlier.
$ oedit /etc/rdz/ssl/ssl.properties
-> change: enable_ssl=true
-> uncomment and change: daemon_keydb_file=rdzssl.kdb
-> uncomment and change: daemon_keydb_password=rsessl
-> uncomment and change: daemon_key_label=rdzrse
-> uncomment and change: server_keystore_file=rdzssl.racf
-> uncomment and change: server_keystore_label=rdzrse
-> uncomment and change: server_keystore_type=JCERACFKS
The preceding changes enable SSL and tell the RSE daemon that the certificate is stored under label rdzrse in key database rdzssl.kdb with password rsessl. RSE server is still using a SAF compliant key ring.
Do not execute this step if you use a SAF-compliant key ring for the RSE server key store.
All information can be passed as a parameter, but due to command-line length limitations some interactivity is required, as follows:
$ cd /etc/rdz/ssl
$ keytool -genkey -alias rdzrse -validity 3650 -keystore rdzssl.jks -storepass
rsessl -keypass rsessl
What is your first and last name?
[Unknown]: rdz rse ssl
What is the name of your organizational unit?
[Unknown]: rdz
What is the name of your organization?
[Unknown]: IBM
What is the name of your City or Locality?
[Unknown]: Raleigh
What is the name of your State or Province?
[Unknown]: NC
What is the two-letter country code for this unit?
[Unknown]: US
Is CN=rdz rse ssl, OU=rdz, O=IBM, L=Raleigh, ST=NC, C=US correct? (type "yes"
or "no")
[no]: yes
$ ls -l rdzssl.*
-rw-r--r-- 1 IBMUSER SYS1 1224 May 24 14:17 rdzssl.jks
The self-signed certificate created in the preceding example is valid for about 10 years (not counting leap days). It is stored in /etc/rdz/ssl/rdzssl.jks using alias rdzrse. Its password (rsessl) is identical to the key store password, which is a requisite for RSE.
The result can be verified with the -list option, as follows:
$ keytool -list -alias rdzrse -keystore rdzssl.jks -storepass rsessl -v
Alias name: rdzrse
Creation date: May 24, 2007
Entry type: keyEntry
Certificate chain length: 1
Certificate 1¨:
Owner: CN=rdz rse ssl, OU=rdz, O=IBM, L=Raleigh, ST=NC, C=US
Issuer: CN=rdz rse ssl, OU=rdz, O=IBM, L=Raleigh, ST=NC, C=US
Serial number: 46562b2b
Valid from: 5/24/07 2:17 PM until: 5/21/17 2:17 PM
Certificate fingerprints:
MD5: 9D:6D:F1:97:1E:AD:5D:B1:F7:14:16:4D:9B:1D:28:80
SHA1: B5:E2:31:F5:B0:E8:9D:01:AD:2D:E6:82:4A:E0:B1:5E:12:CB:10:1C
The following ssl.properties sample shows that the server_* directives differ from the SAF key ring sample shown earlier.
$ oedit /etc/rdz/ssl/ssl.properties
-> change: enable_ssl=true
-> uncomment and change: daemon_keydb_file=rdzssl.racf
-> uncomment and change: daemon_key_label=rdzrse
-> uncomment and change: server_keystore_file=rdzssl.jks
-> uncomment and change: server_keystore_password=rsessl
-> uncomment and change: server_keystore_label=rdzrse
-> optionally uncomment and change: server_keystore_type=JKS
The preceding changes enable SSL and tell the RSE server that the certificate is stored under label rdzrse in key store rdzssl.jks with password rsessl. RSE daemon is still using a SAF-compliant key ring.
This section is provided to assist you with some common problems that you may encounter when setting up Application Transparent Transport Layer Security (AT-TLS), or during checking or modifying an existing setup.
The Transport Layer Security (TLS) protocol defined in RFC 2246 provides communications privacy over the Internet. Similar to its predecessor Secure Socket Layer (SSL), the protocol enables client and server applications to communicate in a way that is designed to prevent eavesdropping, tampering, and message forgery. Application Transparent Transport Layer Security (AT-TLS) consolidates TLS implementation for z/OS-based applications in one location, allowing all applications to support TLS-based encryption without knowledge of the TLS protocol. See Communications Server IP Configuration Guide (SC31-8775) for more information on AT-TLS.
The Integrated Debugger in IBM Rational Developer for System z relies on AT-TLS for encrypted communication with the client, because the data for the debug session does not flow through the same pipe as other Developer for System z client-host communication.
The actions needed to set up AT-TLS will vary from site to site, depending on the exact needs, and depending on what is already available at the site.
Some tasks described in the following sections expect you to be active in z/OS UNIX. This can be done by issuing the TSO command OMVS. Use the oedit command to edit files in z/OS UNIX. Use the exit command to return to TSO.
The TCP/IP documentation recommends writing Policy Agent messages to the z/OS UNIX syslog instead of using the default log file. AT-TLS will always write messages to the z/OS UNIX syslog.
In order to do so, the z/OS UNIX syslog daemon, syslogd, must be configured and active. You will also need a mechanism to control the size of the log files created by syslogd.
syslog 514/udp
# /etc/syslog.conf - control output of syslogd
# 1. all files with will be printed to /tmp/syslog.auth.log
auth.* /tmp/syslog.auth.log
# 2. all error messages printed to /tmp/syslog.error.log
*.err /tmp/syslog.error.log
# 3. all debug and above messages printed to /tmp/syslog.debug.log
*.debug /tmp/syslog.debug.log
# The files named must exist before the syslog daemon is started,
# unless -c startup option is used
# Start the SYSLOGD daemon for logging
# (clean up old logs)
sed -n '/^#/!s/.* \(.*\)/\1/p' /etc/syslog.conf | xargs -i rm {}
# (create new logs and add userid of message sender)
_BPX_JOBNAME='SYSLOGD' /usr/sbin/syslogd -cuf /etc/syslog.conf &
sleep 5
AT-TLS support is activated by the TTLS parameter on the TCPCONFIG statement in the PROFILE.TCPIP data set. AT-TLS is managed by the Policy Agent, which must be active to be able to enforce the AT-TLS policy. Since the Policy Agent must wait for TCP/IP to be active, the AUTOSTART statement in PROFILE.TCPIP is a good place to trigger startup of this server.
TCPCONFIG TTLS ; Required for AT-TLS
AUTOLOG
PAGENT ; POLICY AGENT, required for AT-TLS
ENDAUTOLOG
//PAGENT PROC PRM='-L SYSLOGD' * '' or '-L SYSLOGD'
//*
//* TCP/IP POLICY AGENT
//* (PARM) (envar)
//* default cfg file: /etc/pagent.conf (-C) (PAGENT_CONFIG_FILE)
//* default log file: /tmp/pagent.log (-L) (PAGENT_LOG_FILE)
//* default log size: 300,3 (3x 300KB files) (PAGENT_LOG_FILE_CONTROL)
//*
//PAGENT EXEC PGM=PAGENT,REGION=0M,TIME=NOLIMIT,
// PARM='ENVAR("TZ=EST5DST")/&PRM'
//SYSPRINT DD SYSOUT=*
//SYSOUT DD SYSOUT=*
//*
#
# TCP/IP Policy Agent configuration information.
#
TTLSConfig /etc/pagent.ttls.conf
# Specifies the path of a TTLS policy file holding stack specific
# statements.
#
#TcpImage TCPIP /etc/pagent.conf
# If no TcpImage statement is specified, all policies will be installed
# to the default TCP/IP stack.
#
#LogLevel 31
# The sum of the following values that represent log levels:
# LOGL_SYSERR 1
# LOGL_OBJERR 2
# LOGL_PROTERR 4
# LOGL_WARNING 8
# LOGL_EVENT 16
# LOGL_ACTION 32
# LOGL_INFO 64
# LOGL_ACNTING 128
# LOGL_TRACE 256
# Log Level 31 is the default log loglevel.
#
#Codepage IBM-1047
# Specify the EBCDIC code page to be used for reading all configuration
# files and policy definition files. IBM-1047 is the default code page.
This sample configuration file specifies where the Policy Agent can find the TTLS policy. It uses Policy Agent default values for other statements.
A TTLS policy describes the desired AT-TLS rules. As defined in the Policy Agent configuration file, the TTLS policy is located in /etc/pagent.ttls.conf. The necessary definitions in your security software are covered later.
##
## TCP/IP Policy Agent AT-TLS configuration information.
##
##-----------------------------
TTLSRule RDz_Debug_Manager
{
LocalPortRange 5335
Direction Inbound
TTLSGroupActionRef grp_Production
TTLSEnvironmentActionRef act_RDz_Debug_Manager
}
##-----------------------------
TTLSEnvironmentAction act_RDz_Debug_Manager
{
HandshakeRole Server
TTLSKeyRingParms
{
Keyring dbgmgr.racf # Keyring must be owned by the Debug Manager
}
TTLSEnvironmentAdvancedParms
{
## TLSV1.2 only for z/OS 2.1 and higher
# TLSV1.2 On # SSLv3, TLSv1 & TLSv1.1 are on by default
}
}
##-----------------------------
TTLSRule RDz_Debug_Probe-Client
{
RemotePortRange 8001
Direction Outbound
TTLSGroupActionRef grp_Production
TTLSEnvironmentActionRef act_RDz_Debug_Probe-Client
}
##-----------------------------
TTLSEnvironmentAction act_RDz_Debug_Probe-Client
{
HandshakeRole Client
TTLSKeyRingParms
{
Keyring *AUTH*/* # virtual key ring holding CA certificates
}
TTLSEnvironmentAdvancedParms
{
## TLSV1.2 only for z/OS 2.1 and higher
# TLSV1.2 On # SSLv3, TLSv1 & TLSv1.1 are on by default
}
}
##-----------------------------
TTLSGroupAction grp_Production
{
TTLSEnabled On
## TLSv1.2zOS1.13 only for z/OS 1.13
TTLSGroupAdvancedParmsRef TLSv1.2zOS1.13
Trace 3 # Log Errors to syslogd & IP joblog
#Trace 254 # Log everything to syslogd
}
##-----------------------------
TTLSGroupAdvancedParms TLSv1.2zOS1.13
{
Envfile /etc/pagent.ttls.TLS1.2zOS1.13.env
}
A TTLS policy allows for a wide range of filters to specify when a rule applies.
The Debug Manager is a server that listens on port 5335 for incoming connections from the Debug Engine. This information is captured in the RDz_Debug_Manager rule.
Since SSL and TLS require the usage of a server certificate, you specify that the Policy Manager must use the certificates on the dbgmgr.racf key ring, which is owned by the Debug Manager started task user ID. By default, TLS v1.2 support is disabled, so this policy explicitly enables it.
When the Debug Probe is started with Language Environment (LE) option TEST(,,,TCPIP&&ipaddress%8001:*), it is instructed to not use the Debug Manager but contact the Developer for System z client directly at port 8001. This implies, from a TCP/IP perspective, that the host-based Debug Probe is a client contacting a server (the Debug UI) in the Developer for System z client. This information is captured in the RDz_Debug_Probe-Client rule.
With the host being a TCP/IP client, the Policy Manager will need a way to validate the server certificate presented by the Debug UI. Instead of using a uniformly named key ring for all users that might require an encrypted debug session, we are using RACF’s CERTAUTH virtual key ring (*AUTH*/*). This virtual key ring holds the public certificates of Certificate Authorities (CAs), and can be used if the Debug UI presents a server certificate that is signed by one of the trusted CAs.
Note that for more complex policies, you should use the IBM Configuration Assistant for z/OS Communications Server. This is a GUI-based tool that provides a guided interface for configuring TCP/IP policy-based networking functions and is available as a task in IBM z/OS Management Facility (z/OSMF), and as a stand-alone workstation application.
TLS v1.2 support became available in z/OS 2.1, and is disabled by default. This policy shows the command (TLSV1.2 On) to explicitly enable it, but has it commented out as the target system is using z/OS 1.13.
#
# Add TLSv1.2 support to AT-TLS
# requires z/OS 1.13 with OA39422 and PM62905
#
GSK_RENEGOTIATION=ALL
GSK_PROTOCOL_TLSV1_2=ON
There are several updates required to your security setup for AT-TLS to work properly. This section has sample RACF commands to do the required setup.
# define started task user ID
# BPX.DAEMON permit is required for non-zero UID
ADDUSER PAGENT DFLTGRP(SYS1) OMVS(UID(0) SHARED HOME('/')) +
NAME('TCP/IP POLICY AGENT') NOPASSWORD
# define started task
RDEFINE STARTED PAGENT.* STDATA(USER(PAGENT) GROUP(SYS1)) +
DATA('TCP/IP POLICY AGENT')
# refresh to make the changes visible
SETROPTS RACLIST(STARTED) REFRESH
# restrict startup of policy agent
RDEFINE OPERCMDS MVS.SERVMGR.PAGENT UACC(NONE) +
DATA('restrict startup of policy agent')
PERMIT MVS.SERVMGR.PAGENT CLASS(OPERCMDS) ACCESS(CONTROL) ID(PAGENT)
# refresh to make the changes visible
SETROPTS RACLIST(OPERCMDS) REFRESH
# block stack access between stack and AT-TLS availability
# SETROPTS GENERIC(SERVAUTH)
# SETROPTS CLASSACT(SERVAUTH) RACLIST(FACILITY)
RDEFINE SERVAUTH EZB.INITSTACK.** UACC(NONE)
# Policy Agent
PERMIT EZB.INITSTACK.** CLASS(SERVAUTH) ACCESS(READ) ID(PAGENT)
# OMPROUTE daemon
PERMIT EZB.INITSTACK.** CLASS(SERVAUTH) ACCESS(READ) ID(OMPROUTE)
# SNMP agent and subagents
PERMIT EZB.INITSTACK.** CLASS(SERVAUTH) ACCESS(READ) ID(OSNMPD)
PERMIT EZB.INITSTACK.** CLASS(SERVAUTH) ACCESS(READ) ID(IOBSNMP)
# NAME daemon
PERMIT EZB.INITSTACK.** CLASS(SERVAUTH) ACCESS(READ) ID(NAMED)
# refresh to make the changes visible
SETROPTS RACLIST(SERVAUTH) REFRESH
# restrict access to pasearch command
# RDEFINE SERVAUTH EZB.PAGENT.** UACC(NONE) +
# DATA('restrict access to pasearch command')
# PERMIT EZB.PAGENT.** CLASS(SERVAUTH) ACCESS(READ) ID(tcpadmin)
# refresh to make the changes visible
# SETROPTS RACLIST(SERVAUTH) REFRESH
# permit Debug Manager to access certificates
#RDEFINE FACILITY IRR.DIGTCERT.LIST UACC(NONE)
#RDEFINE FACILITY IRR.DIGTCERT.LISTRING UACC(NONE)
PERMIT IRR.DIGTCERT.LIST CLASS(FACILITY) ACCESS(READ) ID(stcdbm)
PERMIT IRR.DIGTCERT.LISTRING CLASS(FACILITY) ACCESS(READ) ID(stcdbm)
# refresh to make the changes visible
SETROPTS RACLIST(FACILITY) REFRESH
# create self-signed certificate
RACDCERT ID(stcdbm) GENCERT SUBJECTSDN(CN('RDz Debug Manager') +
OU('RTP labs') O('IBM') L('Raleigh') SP('NC') C('US')) +
NOTAFTER(DATE(2015-12-31)) KEYUSAGE(HANDSHAKE) WITHLABEL('dbgmgr')
# (optional) additional steps required to use a signed certificate
# 1. create a signing request for the self-signed certificate
RACDCERT ID(stcdbm) GENREQ (LABEL('dbgmgr')) DSN(dsn)
# 2. send the signing request to your CA of choice
# 3. check if the CA credentials (also a certificate) are already known
RACDCERT CERTAUTH LIST
# 4. mark the CA certificate as trusted
RACDCERT CERTAUTH ALTER(LABEL('CA cert')) TRUST
# or add the CA certificate to the database
RACDCERT CERTAUTH ADD(dsn) WITHLABEL('CA cert') TRUST
# 5. add the signed certificate to the database;
# this will replace the self-signed one
RACDCERT ID(stcdbm) ADD(dsn) WTIHLABEL('dbgmgr') TRUST
# Do NOT delete the self-signed certificate before replacing it.
# If you do, you lose the private key that goes with the certificate,
# which makes the certificate useless.
# create key ring
RACDCERT ID(stcdbm) ADDRING(dbgmgr.racf)
# add certificate to key ring
RACDCERT ID(stcbm) CONNECT(LABEL('dbgmgr') +
RING(dbgmgr.racf) USAGE(PERSONAL) DEFAULT)
# additional step required to use a signed certificate
# 6. add CA certificate to key ring
RACDCERT ID(stcdbm) CONNECT(CERTAUTH LABEL('CA cert') +
RING(dbgmgr.racf))
# refresh to make the changes visible
SETROPTS RACLIST(DIGTCERT) REFRESH
# check if the CA credentials (also a certificate) are already known
RACDCERT CERTAUTH LIST
# mark the CA certificate as trusted
RACDCERT CERTAUTH ALTER(LABEL('CA cert')) TRUST
# or add the CA certificate to the database
RACDCERT CERTAUTH ADD(dsn) WITHLABEL('CA cert') TRUST
# refresh to make the changes visible
SETROPTS RACLIST(DIGTCERT) REFRESH
# verify started task setup
LISTGRP SYS1 OMVS
LISTUSER PAGENT OMVS
RLIST STARTED PAGENT.* ALL STDATA
# verify Policy Agent startup permission
RLIST OPERCMDS MVS.SERVMGR.PAGENT ALL
# verify initstack protection
RLIST SERVAUTH EZB.INITSTACK.** ALL
# verify pasearch protection
RLIST SERVAUTH EZB.PAGENT.** ALL
# verify certificate setup
RACDCERT CERTAUTH LIST(LABEL('CA cert'))
RACDCERT ID(stcdbm) LIST(LABEL('dbgmgr'))
RACDCERT ID(stcdbm) LISTRING(dbgmgr.racf)
TCPCONFIG TTLS
V TCPIP,,OBEY,TCPIP.TCPPARMS(OBEY)
EZZ4249I stackname INSTALLED TTLS POLICY HAS NO RULES
S PAGENT
EZD1586I PAGENT HAS INSTALLED ALL LOCAL POLICIES FOR stackname
P DBGMGR
S DBBMGR
This section is provided to assist you with some common problems that you may encounter when setting up TCP/IP, or during checking or modifying an existing setup.
Refer to Communications Server: IP Configuration Guide (SC31-8775) and Communications Server: IP Configuration Reference (SC31-8776) for additional information on TCP/IP configuration.
When using APPC for the TSO Commands service, Developer for System z is dependent upon TCP/IP having the correct hostname when it is initialized. This implies that the different TCP/IP and Resolver configuration files must be set up correctly.
You can test your TCP/IP configuration with the fekfivpt Installation Verification Program (IVP). The command should return an output like that in this sample ($ is the z/OS UNIX prompt):
$ fekfivpt
Wed Jul 2 13:11:54 EDT 2008
uid=1(USERID) gid=0(GROUP)
using /etc/rdz/rsed.envvars
-------------------------------------------------------------
TCP/IP resolver configuration (z/OS UNIX search order):
-------------------------------------------------------------
Resolver Trace Initialization Complete -> 2008/07/02 13:11:54.745964
res_init Resolver values:
Global Tcp/Ip Dataset = None
Default Tcp/Ip Dataset = None
Local Tcp/Ip Dataset = /etc/resolv.conf
Translation Table = Default
UserId/JobName = USERID
Caller API = LE C Sockets
Caller Mode = EBCDIC
(L) DataSetPrefix = TCPIP
(L) HostName = CDFMVS08
(L) TcpIpJobName = TCPIP
(L) DomainOrigin = RALEIGH.IBM.COM
(L) NameServer = 9.42.206.2
9.42.206.3
(L) NsPortAddr = 53 (L) ResolverTimeout = 10
(L) ResolveVia = UDP (L) ResolverUdpRetries = 1
(*) Options NDots = 1
(*) SockNoTestStor
(*) AlwaysWto = NO (L) MessageCase = MIXED
(*) LookUp = DNS LOCAL
res_init Succeeded
res_init Started: 2008/07/02 13:11:54.755363
res_init Ended: 2008/07/02 13:11:54.755371
************************************************************************
MVS TCP/IP NETSTAT CS V1R9 TCPIP Name: TCPIP 13:11:54
Tcpip started at 01:28:36 on 06/23/2008 with IPv6 enabled
-------------------------------------------------------------
host IP address:
-------------------------------------------------------------
hostName=CDFMVS08
hostAddr=9.42.112.75
bindAddr=9.42.112.75
localAddr=9.42.112.75
Success, addresses match
The resolver acts on behalf of programs as a client that accesses name servers for name-to-address or address-to-name resolution. To resolve the query for the requesting program, the resolver can access available name servers, use local definitions (for example, /etc/resolv.conf, /etc/hosts, /etc/ipnodes, HOSTS.SITEINFO, HOSTS.ADDRINFO or ETC.IPNODES), or use a combination of both.
When the resolver address space starts, it reads an optional resolver setup data set pointed to by the SETUP DD card in the resolver JCL procedure. If the setup information is not provided, the resolver uses the applicable native MVS or z/OS UNIX search order without any GLOBALTCPIPDATA, DEFAULTTCPIPDATA, GLOBALIPNODES, DEFAULTIPNODES or COMMONSEARCH information.
It is important to understand the search order for configuration files used by TCP/IP functions, and when you can override the default search order with environment variables, JCL, or other variables you provide. This knowledge allows you to accommodate your local data set and HFS file naming standards, and it is helpful to know the configuration data set or HFS file in use when diagnosing problems.
Another important point to note is that when a search order is applied for any configuration file, the search ends with the first file found. Therefore, unexpected results are possible if you place configuration information in a file that never gets found, either because other files exist earlier in the search order, or because the file is not included in the search order chosen by the application.
When searching for configuration files, you can explicitly tell TCP/IP where most configuration files are by using DD statements in the JCL procedures or by setting environment variables. Otherwise, you can let TCP/IP dynamically determine the location of the configuration files, based on search orders documented in Communications Server: IP Configuration Guide (SC31-8775).
The TCP/IP stack’s configuration component uses TCPIP.DATA during TCP/IP stack initialization to determine the stack’s HOSTNAME. To get its value, the z/OS UNIX environment search order is used.
The particular file or table that is searched for can be either an MVS data set or an HFS file, depending on the resolver configuration settings and the presence of given files on the system.
The base resolver configuration file contains TCPIP.DATA statements. In addition to resolver directives, it is referenced to determine, among other things, the data set prefix (DATASETPREFIX statement’s value) to be used when trying to access some of the configuration files specified in this section.
The search order used to access the base resolver configuration file is the following:
If defined, the resolver GLOBALTCPIPDATA setup statement value is used (see also Understanding resolvers). The search continues for an additional configuration file. The search ends with the next file found.
The value of the environment variable is used. This search will fail if the file does not exist or is allocated exclusively elsewhere.
The data set allocated to the DD name SYSTCPD is used. In the z/OS UNIX environment, a child process does not have access to the SYSTCPD DD. This is because the SYSTCPD allocation is not inherited from the parent process over the fork() or exec function calls.
userid is the user ID that is associated with the current security environment (address space, task, or thread).
jobname is the name specified on the JOB JCL statement for batch jobs or the procedure name for a started procedure.
If defined, the resolver DEFAULTTCPIPDATA setup statement value is used (see also Understanding resolvers).
The translate tables (EBCDIC-to-ASCII and ASCII-to-EBCDIC) are referenced to determine the translate data sets to be used. The search order used to access this configuration file is the following. The search order ends at the first file being found:
userid is the user ID that is associated with the current security environment (address space or task/thread).
jobname is the name specified on the JOB JCL statement for batch jobs or the procedure name for a started procedure.
hlq represents the value of the DATASETPREFIX statement specified in the base resolver configuration file (if found); otherwise, hlq is TCPIP by default.
By default, resolver first attempts to use any configured domain name servers for resolution requests. If the resolution request cannot be satisfied, local host tables are used. Resolver behavior is controlled by TCPIP.DATA statements.
The TCPIP.DATA resolver statements define if and how domain name servers are to be used. The LOOKUP TCPIP.DATA statement can also be used to control how domain name servers and local host tables are used. For more information on TCPIP.DATA statements, refer to Communications Server: IP Configuration Reference (SC31-8776).
The resolver uses the Ipv4-unique search order for sitename information unconditionally for getnetbyname API calls. The Ipv4-unique search order for sitename information is the following. The search ends at the first file being found:
The value of the environment variable is the name of the HOSTS.SITEINFO information file created by the TSO MAKESITE command.
The value of the environment variable is the name of the HOSTS.ADDRINFO information file created by the TSO MAKESITE command.
userid is the user ID that is associated with the current security environment (address space or task/thread).
jobname is the name specified on the JOB JCL statement for batch jobs or the procedure name for a started procedure.
hlq represents the value of the DATASETPREFIX statement specified in the base resolver configuration file (if found); otherwise, hlq is TCPIP by default.
As stated before, Developer for System z is dependent upon TCP/IP having the correct hostname when it is initialized, when using APPC. This implies that the different TCP/IP and Resolver configuration files must be set up correctly.
The following example focuses on some configuration tasks for TCP/IP and Resolver. Note that this does not cover a complete setup of TCP/IP or Resolver, it just highlights some key aspects that might be applicable to your site:
//TCPIP PROC PARMS=’CTRACE(CTIEZB00)’,PROF=TCPPROF,DATA=TCPDATA
//*
//* TCP/IP NETWORK
//*
//TCPIP EXEC PGM=EZBTCPIP,REGION=0M,TIME=1440,PARM=&PARMS
//PROFILE DD DISP=SHR,DSN=SYS1.TCPPARMS(&PROF)
//SYSTCPD DD DISP=SHR,DSN=SYS1.TCPPARMS(&DATA)
//SYSPRINT DD SYSOUT=*,DCB=(RECFM=VB,LRECL=132,BLKSIZE=136)
//ALGPRINT DD SYSOUT=*,DCB=(RECFM=VB,LRECL=132,BLKSIZE=136)
//CFGPRINT DD SYSOUT=*,DCB=(RECFM=VB,LRECL=132,BLKSIZE=136)
//SYSOUT DD SYSOUT=*,DCB=(RECFM=VB,LRECL=132,BLKSIZE=136)
//CEEDUMP DD SYSOUT=*,DCB=(RECFM=VB,LRECL=132,BLKSIZE=136)
//SYSERROR DD SYSOUT=*
; HOSTNAME specifies the TCP host name of this system. If not
; specified, the default HOSTNAME will be the node name specified
; in the IEFSSNxx PARMLIB member.
;
; HOSTNAME
;
; DOMAINORIGIN specifies the domain origin that will be appended
; to host names passed to the resolver. If a host name contains
; any dots, then the DOMAINORIGIN will not be appended to the
; host name.
;
DOMAINORIGIN RALEIGH.IBM.COM
;
; NSINTERADDR specifies the IP address of the name server.
; LOOPBACK (14.0.0.0) specifies your local name server. If a name
; server will not be used, then do not code an NSINTERADDR statement.
; (Comment out the NSINTERADDR line below). This will cause all names
; to be resolved via site table lookup.
;
; NSINTERADDR 14.0.0.0
;
; TRACE RESOLVER will cause a complete trace of all queries to and
; responses from the name server or site tables to be written to
; the user’s console. This command is for debugging purposes only.
;
; TRACE RESOLVER
//RESOLVER PROC PARMS=’CTRACE(CTIRES00)’
//*
//* IP NAME RESOLVER – START WITH SUB=MSTR
//*
//RESOLVER EXEC PGM=EZBREINI,REGION=0M,TIME=1440,PARM=&PARMS
//*SETUP DD DISP=SHR,DSN=USER.PROCLIB(RESSETUP),FREE=CLOSE
TCPIPJOBNAME TCPIP
DomainOrigin RALEIGH.IBM.COM
HostName CDFMVS08
As mentioned in Search orders used in the z/OS UNIX environment, the base configuration file contains TCPIP.DATA statements. If the system name is CDFMVS08 (TCPDATA stated that the system name is used as hostname) you can see that /etc/resolv.conf is in sync with SYS1.TCPPARMS(TCPDATA). There are no DNS definitions so site table lookup will be used.
# Resolver /etc/hosts file cdfmvs08
9.42.112.75 cdfmvs08 # CDFMVS08 Host
9.42.112.75 cdfmvs08.raleigh.ibm.com # CDFMVS08 Host
127.0.0.1 localhost
The minimal content of this file is information about the current system. In the preceding sample, both cdfmvs08 and cdfmvs08.raleigh.ibm.com are defined as a valid name for the IP address of the z/OS system.
If you were using a domain name server (DNS), the DNS would hold the /etc/hosts info, and /etc/resolv.conf and SYS1.TCPPARMS(TCPDATA) would have statements that identify the DNS to your system.
To avoid confusion, you should keep the TCP/IP and Resolver configuration files in sync with each other.
File type description | APIs affected | Candidate files |
---|---|---|
Base resolver configuration files | All APIs |
|
Translate tables | All APIs |
|
Local host tables | endhostent |
IPv4
IPv6
|
clientip(0.0.0.0) <> callerip(<host IP address>)
Resolver Trace Initialization Complete -> 2008/07/02 13:11:54.745964
res_init Resolver values:
Global Tcp/Ip Dataset = None
Default Tcp/Ip Dataset = None
Local Tcp/Ip Dataset = /etc/resolv.conf
Translation Table = Default
UserId/JobName = USERID
Caller API = LE C Sockets
Caller Mode = EBCDIC
Ensure that the definitions in the file (or data set) referenced by “Local Tcp/Ip Dataset” are correct.
This field will be blank if you do not use a default name for the IP resolver file (using the z/OS UNIX search order). If so, add the following statement to rsed.envvars, where <resolver file> or <resolver data> represents the name of your IP resolver file:
RESOLVER_CONFIG=<resolver file>
or
RESOLVER_CONFIG=’<resolver data set>’
The following publications are referenced in this document:
Publication title | Order number | Reference | Reference Web site |
---|---|---|---|
Program Directory for IBM Rational Developer for System z | GI11-8298 | Developer for System z | http://www-01.ibm.com/support/docview.wss?uid=swg27038517 |
Program Directory for IBM Rational Developer for System z Host Utilities | GI13-2864 | Developer for System z | http://www-01.ibm.com/support/docview.wss?uid=swg27038517 |
IBM Rational Developer for System z Prerequisites | SC23-7659 | Developer for System z | http://www-01.ibm.com/support/docview.wss?uid=swg27038517 |
IBM Rational Developer for System z Host Configuration Quick Start | GI11-9201 | Developer for System z | http://www-01.ibm.com/support/docview.wss?uid=swg27038517 |
IBM Rational Developer for System z Host Configuration Guide | SC23-7658 | Developer for System z | http://www-01.ibm.com/support/docview.wss?uid=swg27038517 |
IBM Rational Developer for System z Host Configuration Reference | SC14-7290 | Developer for System z | http://www-01.ibm.com/support/docview.wss?uid=swg27038517 |
IBM Rational Developer for System z Host Configuration Utility Guide | SC14-7282 | Developer for System z | http://www-01.ibm.com/support/docview.wss?uid=swg27038517 |
IBM Rational Developer for System z Messages and Codes | SC14-7497 | Developer for System z | http://www-01.ibm.com/support/docview.wss?uid=swg27038517 |
IBM Rational Developer for System z Answers to common host configuration and maintenance issues | SC14-7373 | Developer for System z | http://www-01.ibm.com/support/docview.wss?uid=swg27038517 |
IBM Rational Developer for System z Common Access Repository Manager Developer's Guide | SC23-7660 | Developer for System z | http://www-01.ibm.com/support/docview.wss?uid=swg27038517 |
IBM Rational Developer for System z Prerequisites | SC23-7659 | Developer for System z | http://www.ibm.com/software/rational/products/developer/systemz/library/index.html |
IBM Rational Developer for System z Host Configuration Quick Start | GI11-9201 | Developer for System z | http://www.ibm.com/software/rational/products/developer/systemz/library/index.html |
SCLM Developer Toolkit Administrator's Guide | SC23-9801 | Developer for System z | http://www-01.ibm.com/support/docview.wss?uid=swg27038517 |
Using APPC to provide TSO command services | SC14-7291 | White paper | http://www-01.ibm.com/support/docview.wss?uid=swg27038517 |
Using ISPF Client Gateway to provide CARMA services | SC14-7292 | White paper | http://www-01.ibm.com/support/docview.wss?uid=swg27038517 |
Communications Server IP Configuration Guide | SC31-8775 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
Communications Server IP Configuration Reference | SC31-8776 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
Communications Server IP Diagnosis Guide | GC31-8782 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
Communications Server IP System Administrator's Commands | SC31-8781 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
Communications Server SNA Network Implementation Guide | SC31-8777 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
Communications Server SNA Operations | SC31-8779 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
Cryptographic Services System SSL Programming | SC24-5901 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
DFSMS Macro Instructions for Data Sets | SC26-7408 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
DFSMS Using data sets | SC26-7410 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
Language Environment Customization | SA22-7564 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
Language Environment Debugging Guide | GA22-7560 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
MVS Diagnosis: Tools and Service Aids | GA22-7589 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
MVS Initialization and Tuning Guide | SA22-7591 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
MVS Initialization and Tuning Reference | SA22-7592 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
MVS JCL Reference | SA22-7597 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
MVS Planning APPC/MVS Management | SA22-7599 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
MVS Planning Workload Management | SA22-7602 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
MVS System Commands | SA22-7627 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
Security Server RACF Command Language Reference | SA22-7687 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
Security Server RACF Security Administrator's Guide | SA22-7683 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
TSO/E Customization | SA22-7783 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
TSO/E REXX Reference | SA22-7790 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
UNIX System Services Command Reference | SA22-7802 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
UNIX System Services Planning | GA22-7800 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
UNIX System Services User's Guide | SA22-7801 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
Using REXX and z/OS UNIX System Services | SA22-7806 | z/OS 1.13 | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
Java™ Diagnostic Guide | SC34-6650 | Java 6.0 | http://www.ibm.com/developerworks/java/jdk/diagnosis/ |
Java SDK and Runtime Environment User Guide | / | Java 6.0 | http://www-03.ibm.com/servers/eserver/zseries/software/java/ |
Resource Definition Guide | SC34-6430 | CICSTS 3.1 | http://www-03.ibm.com/systems/z/os/zos/bkserv/zapplsbooks.html |
Resource Definition Guide | SC34-6815 | CICSTS 3.2 | http://www-03.ibm.com/systems/z/os/zos/bkserv/zapplsbooks.html |
Resource Definition Guide | SC34-7000 | CICSTS 4.1 | https://publib.boulder.ibm.com/infocenter/cicsts/v4r1/index.jsp?topic=/com.ibm.cics.ts.home.doc/library/library_html.html |
Resource Definition Guide | SC34-7181 | CICSTS 4.2 | https://publib.boulder.ibm.com/infocenter/cicsts/ v4r2/index.jsp?topic=/com.ibm.cics.ts.home.doc/ library/library_html.html |
RACF Security Guide | SC34-6454 | CICSTS 3.1 | http://www-03.ibm.com/systems/z/os/zos/bkserv/zapplsbooks.html |
RACF Security Guide | SC34-6835 | CICSTS 3.2 | http://www-03.ibm.com/systems/z/os/zos/bkserv/zapplsbooks.html |
RACF Security Guide | SC34-7003 | CICSTS 4.1 | https://publib.boulder.ibm.com/infocenter/cicsts/v4r1/index.jsp?topic=/com.ibm.cics.ts.home.doc/library/library_html.html |
RACF Security Guide | SC34-7179 | CICSTS 4.2 | https://publib.boulder.ibm.com/infocenter/cicsts/v4r2/index.jsp?topic=/com.ibm.cics.ts.home.doc/library/library_html.html |
Language Reference | SC27-1408 | Enterprise COBOL for z/OS | http://www-03.ibm.com/systems/z/os/zos/bkserv/zapplsbooks.html |
Description | Reference Web site |
---|---|
Developer for System z IBM Knowledge Center | http://www-01.ibm.com/support/knowledgecenter/SSQ2R2_9.1.0/com.ibm.etools.getstart.wsentdev.doc/kc_version_welcome_rdz.html |
Developer for System z Library | http://www-01.ibm.com/support/docview.wss?uid=swg27038517 |
Developer for System z home page | http://www-03.ibm.com/software/products/en/developerforsystemz/ |
Developer for System z Recommended service | http://www-01.ibm.com/support/docview.wss?rs=2294&context=SS2QJ2&uid=swg27006335 |
Developer for System z enhancement request | https://www.ibm.com/developerworks/support/rational/rfe/ |
z/OS internet library | http://www-03.ibm.com/servers/eserver/zseries/zos/bkserv/ |
CICSTS IBM Knowledge Center | https://publib.boulder.ibm.com/infocenter/cicsts/v4r1/index.jsp |
IBM Tivoli Directory Server | http://www-01.ibm.com/software/tivoli/products/directory-server/ |
Problem Determination Tools Plug-ins | http://www-01.ibm.com/software/awdtools/deployment/pdtplugins/ |
Java security information | http://www.ibm.com/developerworks/java/jdk/security/ |
Download Apache Ant | http://ant.apache.org/ |
Java keytool documentation | http://java.sun.com/j2se/1.5.0/docs/tooldocs/solaris/keytool.html |
CA support home page | https://support.ca.com/ |
Publication title | Order number | Reference | Reference website |
---|---|---|---|
ABCs of z/OS System Programming Volume 9 (z/OS UNIX) | SG24-6989 | Redbook | http://www.redbooks.ibm.com/ |
System Programmer’s Guide to: Workload Manager | SG24-6472 | Redbook | http://www.redbooks.ibm.com/ |
TCPIP Implementation Volume 1: Base Functions, Connectivity, and Routing | SG24-7532 | Redbook | http://www.redbooks.ibm.com/ |
TCPIP Implementation Volume 3: High Availability, Scalability, and Performance | SG24-7534 | Redbook | http://www.redbooks.ibm.com/ |
TCP/IP Implementation Volume 4: Security and Policy-Based Networking | SG24-7535 | Redbook | http://www.redbooks.ibm.com/ |
Tivoli Directory Server for z/OS | SG24-7849 | Redbook | http://www.redbooks.ibm.com/ |
© Copyright IBM Corporation 1992, 2013.
U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte character set (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to:
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan, Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan
The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.
Any references in this information to non-IBM websites are provided for convenience only and do not in any manner serve as an endorsement of those websites. The materials at those websites are not part of the materials for this IBM product and use of those websites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:
Intellectual Property Dept. for Rational Software
IBM Corporation
Silicon Valley Lab
555 Bailey Avnue
San Jose, CA 95141-1003
U.S.A.
Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of 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.
All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.
This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs.
Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows:
© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. © Copyright IBM Corp. 1992, 2013.
If you are viewing this information in softcopy, the photographs and color illustrations may not appear.
IBM Software products, including software as a service solutions, (“Software Offerings”) may use cookies or other technologies to collect product usage information, to help improve the end user experience, to tailor interactions with the end user or for other purposes. In many cases no personally identifiable information is collected by the Software Offerings. Some of our Software Offerings can help enable you to collect personally identifiable information. If this Software Offering uses cookies to collect personally identifiable information, specific information about this offering’s use of cookies is set forth below.
This Software Offering does not use cookies or other technologies to collect personally identifiable information.
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the web at "Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.
Applicability
These terms and conditions are in addition to any terms of use for the IBM website.
Personal use
You may reproduce these publications for your personal, noncommercial use provided that all proprietary notices are preserved. You may not distribute, display or make derivative work of these publications, or any portion thereof, without the express consent of IBM.
Commercial use
You may reproduce, distribute and display these publications solely within your enterprise provided that all proprietary notices are preserved. You may not make derivative works of these publications, or reproduce, distribute or display these publications or any portion thereof outside your enterprise, without the express consent of IBM.
Rights
Except as expressly granted in this permission, no other permissions, licenses or rights are granted, either express or implied, to the publications or any information, data, software or other intellectual property contained therein.
IBM reserves the right to withdraw the permissions granted herein whenever, in its discretion, the use of the publications is detrimental to its interest or, as determined by IBM, the above instructions are not being properly followed.
You may not download, export or re-export this information except in full compliance with all applicable laws and regulations, including all United States export laws and regulations.
IBM MAKES NO GUARANTEE ABOUT THE CONTENT OF THESE PUBLICATIONS. THE PUBLICATIONS ARE PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE.
This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs.
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at www.ibm.com/legal/copytrade.shtml.
Adobe and PostScript are trademarks of Adobe Systems Incorporated.
Cell Broadband Engine - Sony Computer Entertainment Inc.
Rational is a trademark of International Business Machines Corporation and Rational Software Corporation, in the United States, other countries, or both.
Intel, Intel Centrino, Intel SpeedStep, Intel Xeon, Celeron, Itanium, and Pentium are trademarks of Intel Corporation in the United States, or other countries, or both.
IT Infrastructure Library is a trademark of Central Computer and Telecommunications Agency
ITIL is a trademark of The Minister for the Cabinet Office
Linear Tape-Open, LTO, and Ultrium are trademarks of HP, IBM Corp., and Quantum
Linux is a trademark of Linus Torvalds
Microsoft, Windows, and the Windows logo are trademarks or registered trademarks of Microsoft Corporation in the United States, or other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.
UNIX is a registered trademark of The Open Group in the United States and other countries.