Defining RRSF nodes to RACF

The TARGET command specifies the operational characteristics of a node with which the local node is to communicate. Each node that the local node expects to communicate with must be defined by a TARGET command, including the local node itself. These nodes are referred to as target nodes

TARGET is an operator command, and it can be issued in three different ways:

An operator can enter the command manually, at the console.
An operator can enter a SET INCLUDE(xx) command at the console, where xx specifies a member of the RACF® parameter library that issues a TARGET command, or includes another member that does.
RACF subsystem initialization can automatically invoke a member of the RACF parameter library that invokes a TARGET command, or includes another member that does. The member is specified as a parameter in the RACF PROC.

For the syntax of the TARGET command, see z/OS Security Server RACF Command Language Reference. For information on establishing security for the TARGET command, see z/OS Security Server RACF Security Administrator's Guide.

You must specify a node name, workspace information, and the high level qualifiers to be used on the INMSG and OUTMSG data sets for the node before you can make the connection with the node operative. In addition, if the node is not running in local mode, you must also specify protocol information before you can make the connection with the node operative. You can also specify a description of the node.

An MVS™ system image must meet the following requirements to be defined as an RRSF node:

The RACF component of the z/OS Security Server is enabled.
The RACF subsystem address space is active.

TARGET commands are cumulative. That is, you can specify a subset of the configuration information for a node on one TARGET command, and additional information for the same node on subsequent TARGET commands.

For APPC connections, once you specify OPERATIVE or DORMANT on a TARGET command for a node, RACF activates the node or makes it dormant, and any further TARGET commands that attempt to change the specification of the protocol or workspace data sets for a node are rejected. To change the protocol or workspace data set specification, you must delete the node and then redefine it.
For TCP/IP connections, once you specify OPERATIVE on a TARGET command for a node, RACF activates the node and any further TARGET commands that attempt to change the specification of the protocol or workspace data sets for a node are rejected. However, you can change the protocol information if the node is dormant.

Tip: When defining or changing an RRSF network, first test the TARGET commands by entering them manually at the console. When you are satisfied that they are correct, add them to a RACF parameter library member that is invoked by RACF subsystem initialization, so that the changes persist over system IPLs or if the RACF subsystem address space is stopped and restarted. Keep in mind that you will probably need to make corresponding changes to parameter library members on remote nodes.

You must define the local node and the local node must be in an operative state before you can make connections to other nodes operative. The listener for the protocol used must be active before you can make a connection operative. In addition, if the local node is a multisystem node you must define the main system of the remote node before you can make any system in that remote node operative.

RACF cannot determine whether the member systems of a multisystem node share a RACF database. If you configure a multisystem node, you must ensure that its member systems share a RACF database.

RACF checks the TARGET commands issued for a node by that node and by other nodes, and can detect mismatches in:

LU names (for APPC only)
Node names
System names
Protocol
The system designated to be the main system
A node's definition as a multisystem node or a single-system RRSF node

For example, assume NODEA, NODEB, and NODEC all use APPC and have LU names LUA, LUB, and LUC respectively, and that NODEB and NODEC issue correct TARGET commands. Assume that NODEA incorrectly specifies LUC for NODEB and LUB for NODEC on its TARGET commands. When NODEA issues a TARGET OPERATIVE command for NODEC, RACF determines that there is a mismatch between the LU name specified for NODEC on NODEA and the LU name specified for NODEC on NODEC. RACF sets the connection to the operative pending verification state, and issues message IRRI014I. The message contains a reason code to help diagnose the mismatch so that the TARGET commands can be redone. (For TCP/IP connections, RACF issues message IRRI016I instead of IRRI014I.)

Use the NODE keyword on the TARGET command to specify a name for a node. This is the name that users will specify on the RACLINK command and the AT and ONLYAT keywords to identify the node. Therefore, the name should be something that is meaningful to users.

Use the SYSNAME keyword with the NODE keyword to identify which system on a multisystem node the command pertains to. If you specify the SYSNAME keyword, you must also specify the NODE keyword. The SYSNAME keyword is required on TARGET commands for multisystem nodes, unless the LIST keyword is specified or defaulted to. (See Listing the attributes of target nodes for information on when the LIST keyword is defaulted to.) If SYSNAME is not specified, and LIST is not specified or used as the default, RACF assumes that the node is a single-system node.

The value of SYSNAME must match the value in the CVTSNAME field of the system the TARGET command describes. This is the SYSNAME specified in the IEASYSxx member of SYS1.PARMLIB. Because it is used as a data set qualifier for the local node's workspace data sets, SYSNAME should not have a numeric as the first character. If the value of SYSNAME begins with a numeric that cannot be changed, specify WDSQUAL on the TARGET command to provide a replacement value for the data set qualifier in the local node's workspace data set name.

You can specify an asterisk on the SYSNAME keyword to indicate that the command should be executed for each system in the multisystem node specified by the NODE keyword. For example, if you specify SYSNAME(*) with the LIST keyword and a NODE keyword of NODE(HURLEY), RACF generates a list for each system in the multisystem node named HURLEY. You can specify an asterisk on the SYSNAME keyword only in combination with the following keywords:

NODE
DORMANT
OPERATIVE
DELETE
PURGE
LIST

If LIST is specified with NODE(*), SYSNAME must be specified as SYSNAME(*) or omitted.

The SYSNAME keyword allows you to use a common set of TARGET commands on all the systems in a multisystem node. When the TARGET command is for a local node, and the OPERATIVE or DORMANT keyword is specified, RACF compares the SYSNAME specified on the TARGET command with the CVTSNAME for the system the command is to run on. If they do not match, RACF does not process the OPERATIVE or DORMANT keyword. In addition, because a conversation should not exist between the systems of a multisystem node, RACF issues an informational message and places it in the SYSLOG. This message might help diagnose why an expected conversation was not established.

Use the MAIN keyword to identify the system named on the SYSNAME keyword as the main system in a multisystem RRSF node. (For information about the main system, see Single-system nodes and multisystem nodes.) You must issue a TARGET command identifying the main system for a multisystem node on each system in the multisystem node, and on each RRSF node that communicates with the multisystem node. You must designate the same system as the main system on the local node and all other nodes that communicate with it. You must identify the main system of a multisystem node before you make any systems in the multisystem node operative.

Because the main system in a multisystem node receives the majority of RRSF traffic to the node, be sure to select a main system that can handle the RRSF traffic. To minimize the time that RRSF requests will have to be kept in workspace data sets while the system is unavailable, the main system should also be the system least likely to need hardware or software changes. When deciding the file size for the main system, consider the volume of RRSF traffic the system will handle, and the amount of time it might be unavailable.

Use the LOCAL keyword on the TARGET command to identify the node you are defining as the local node. If you do not specify LOCAL, RACF assumes that the node is a remote node. You can only define one local node. Once you have defined a node as the local node, you do not have to specify LOCAL on subsequent TARGET commands for that node. If you plan to run in local mode, the only TARGET command you need is one for the local node.

Use the DESCRIPTION keyword on the TARGET command to specify a description of the node you are defining. The description is displayed in the TARGET LIST output for the node.

Use the PROTOCOL keyword to indicate that the node being defined is to run in remote mode, and to specify the network transport mechanism to be used. Specify either APPC or TCP. The subkeywords of PROTOCOL specify information about the network transport mechanism. Protocol information is required in order to communicate with remote nodes. Protocol information should not be specified for a node running in local mode. If it is specified, unnecessary processing occurs.

If you specify APPC for the protocol, use the LUNAME subkeyword on the PROTOCOL(APPC()) keyword to identify the logical unit to be associated with the RRSF node being defined. Specify a 1-to-8-character LU name, or a qualified LU name in the form netid.luname, where netid is a 1-to-8-character network name, and luname is a 1-to-8-character LU name. You can find the LU name in the SYS1.PARMLIB APPCPMxx member on the target node you are defining. (The name specified on the ACBNAME keyword is the LU name.) You can also use the DISPLAY APPC operator command on a node to display its LU name. See z/OS MVS Planning: APPC/MVS Management for information on the DISPLAY APPC command. Some points to keep in mind:

You must specify the LU name for a node before you can make the connection with that node operative.
You can modify a node's LU name only while the node is in the initial state.
If you specify the same LU name on multiple TARGET commands, the first usage takes precedence. For example, if you issue two TARGET commands for different node names, but with the same LU names, the node specified on the first TARGET command is associated with the LU name, and a message is issued when the second TARGET command is issued.
On the local system, you must specify an LU name in the target definitions for the local peer members, even though conversations do not occur with these members. And the LU name specified for a particular remote target definition must match the LU name specified on all the local peer systems for their corresponding remote target definitions. If you later reconfigure the multisystem node with a new main system, the old main system's workspace data sets will be accessed by the new main system. If the LU names are not the same, the reconfiguration will not work.
If the LU name is a qualified name in the form netid.luname, RACF uses only the second part of the qualified name as a qualifier for the workspace data set names. If the second part of the qualified LU name is not unique within the group of DASD devices shared by the local system, you must use the WDSQUAL keyword to supply a unique qualifier for the workspace data set names.

If you specify APPC for the protocol, use the optional TPNAME subkeyword on the PROTOCOL(APPC()) keyword to identify the APPC transaction program (TP) profile. The TP profile name is 1 - 64 characters in length, and defaults to IRRRACF. Once you have specified a TP profile name for a node, you can change it only if you first make the node dormant.

Guideline: Let RACF take the default and use IRRRACF as the TPNAME unless you need to change it.

If you specify APPC for the protocol, use the optional MODENAME subkeyword on the PROTOCOL(APPC()) keyword to specify the mode name which designates the network properties for the session to be allocated. The mode name is an alphanumeric string 1 - 8 characters in length. If you do not specify a mode name, the TARGET LIST output shows the mode name as <NOT SPECIFIED>, and RACF uses the default name IRRMODE. VTAM® issues an error message, and uses the default values for the session. If you want to prevent the error message from VTAM, use the sample VTAM LOGMODE entry for IRRMODE provided in member IRRSRRSF in SYS1.SAMPLIB. Once you have specified the APPC mode name for a node, you can change it only if you first make the node dormant.

If you specify TCP for the protocol, use the ADDRESS subkeyword on the PROTOCOL(TCP()) keyword to identify the remote system. Specify either the host name of the target system or its static IP address. ADDRESS is not required for the local node, and if not specified, RACF uses the default value of 0.0.0.0. ADDRESS must be specified for a remote node before a TARGET command making it operative is issued. An IP address may be specified as an IPv4 address or an IPv6 address (if TCP IPv6 is enabled on the system). See z/OS Communications Server: IPv6 Network and Application Design Guide for more information about the IPv6 protocol in z/OS® Communication Server.

If you specify TCP for the protocol, use the optional PORTNUM subkeyword on the PROTOCOL(TCP()) keyword to specify the port on which the RRSF node will establish a socket in order to listen for requests initiated by a remote node. If not specified, the default value is 18136.

Guideline: Use the default value for PORTNUM.

Use the PREFIX keyword to specify one or more high-level qualifiers for the data set names of the INMSG and OUTMSG workspace data sets. The maximum length of the prefix is 19 characters, and it can contain multiple qualifiers separated by periods. Your prefix should not end in a period, as RACF appends one to the end for you. Keep in mind when defining your prefix that, as for all data sets, the high-level qualifier of the workspace data sets must be a RACF-defined user ID or group name.

Guideline: Specify the same prefix for all systems on a multisystem node, to allow you to reconfigure the multisystem node with a different main system. On the local system the prefix specified for a particular remote target definition must match the prefix specified on all the local peer systems for their corresponding remote target definitions. For example, if system MVSB of local node NODEAB defines the prefix for remote node NODEZ to be SYSZ, system MVSA of local node NODEAB must also define the prefix for remote node NODEZ to be SYSZ. If you later reconfigure the multisystem node with a new main system, the old main system's workspace data sets will be accessed by the new main system. If the prefixes are not the same, the reconfiguration will not work.

Use the WDSQUAL keyword to specify a qualifier for a workspace data set name that RACF is to use instead of the value it uses by default.

For a local node, use the WDSQUAL keyword to provide an alternative to the name specified on the SYSNAME keyword. If the system name specified on SYSNAME begins with a numeric character, you must specify WDSQUAL to provide a qualifier for the workspace data set names that does not begin with a numeric.
For a remote node, use the WDSQUAL keyword to provide an alternative to the name specified on the LUNAME keyword for an APPC connection, or to the name specified on the NODE keyword for a TCP/IP connection to a single-system node, or to the name specified on the SYSNAME keyword for a TCP/IP connection to a multisystem node. For an APPC connection, if the LU name is a qualified name, and the second part of the name would not be a unique data set qualifier within the group of DASD devices shared by the local system, you must use the WDSQUAL keyword to provide a unique qualifier for the workspace data set names.

If you specify the WDSQUAL keyword, you are responsible for ensuring that the resulting workspace data set names do not conflict with the workspace data set names for any other nodes. For more information on the workspace data sets, see Workspace data sets.

Use the WORKSPACE keyword to specify the attributes of the workspace data sets. There is an INMSG and OUTMSG workspace data set for each target node. You can preallocate the VSAM files for the workspace data sets yourself, or let RACF allocate them. If you preallocate the VSAM files, you do not need to specify the WORKSPACE keyword. For more information on the INMSG and OUTMSG workspace data sets, see Workspace data sets.

Protect the workspace data sets you define from viewing, reading, and writing by unauthorized users. The user ID assigned to the RACF subsystem must have authority to allocate and write to these data sets.

You can specify either a System Managed Storage (SMS) or non-SMS workspace. It is very important that the workspace data sets do not run out of space. Guideline: Create the workspace data sets as SMS-managed data sets that can grow as needed.

Use the STORCLAS, DATACLAS, and MGMTCLAS subkeywords on the WORKSPACE keyword to specify an SMS workspace. You must specify STORCLAS for an SMS workspace if you have not preallocated the VSAM files; DATACLAS and MGMTCLAS are optional.
Use the VOLUME subkeyword on the WORKSPACE keyword to specify a non-SMS workspace. The volume serial number specified must be a valid volume on the system where the TARGET command is issued.

Guideline: For multisystem nodes, allocate the workspace data sets on shared DASD using shared catalogs. Doing this allows you to share one set of TARGET definitions for all systems in a multisystem node.

Use the optional FILESIZE subkeyword on the WORKSPACE keyword to specify how much space to allocate for the workspace data sets. Enough space is allocated for each data set to contain the number of entries specified on the FILESIZE subkeyword. Specify a number in the range 1 - 2147483647. The initial value is FILESIZE(500). For some guidelines on what size to specify, see Size guidelines for the workspace data sets.