ADDGROUP (Add group profile)

Purpose

Use the ADDGROUP command to define a new group to RACF®.

The command adds a profile for the new group to the RACF database. It also establishes the relationship of the new group to the superior group you specify.

Group profiles consist of a BASE segment and, optionally, other segments such as DFP and OMVS. You can use this command to specify information in any segment of the profile.

Issuing options

The following table identifies the eligible options for issuing the ADDGROUP command:

For information on issuing this command as a RACF TSO command, refer to RACF TSO commands.

For information on issuing this command as a RACF operator command, refer to RACF operator commands.

You must be logged on to the console to issue this command as a RACF operator command.

Related commands

• To delete a group profile, see DELGROUP (Delete group profile).
• To change a group profile, see ALTGROUP (Alter group profile).
• To connect a user to a group, see CONNECT (Connect user to group).
• To remove a user from a group, see REMOVE (Remove user from group).
• To obtain a list of group profiles, see SEARCH (Search RACF database).
• To list a group profile, see LISTGRP (List group profile).

Authorization required

When issuing this command as a RACF operator command, you might require sufficient authority to the proper resource in the OPERCMDS class. For details about OPERCMDS resources, see "Controlling the use of operator commands" in z/OS Security Server RACF Security Administrator's Guide.

To add segments, such as DFP or OMVS, to a group's profile, you must have at least one of the following authorizations:

For information on field-level access checking, see z/OS Security Server RACF Security Administrator's Guide.

To specify the AT keyword, you must have READ authority to the DIRECT.node resource in the RRSFDATA class and a user ID association must be established between the specified node.userid pair(s).

To specify the ONLYAT keyword you must have the SPECIAL attribute, the userid specified on the ONLYAT keyword must have the SPECIAL attribute, and a user ID association must be established between the specified node.userid pair(s) if the user IDs are not identical.

To specify the SHARED keyword, you must have the SPECIAL attribute or at least READ authority to the SHARED.IDS resource in the UNIXPRIV class.

Parameters

subsystem-prefix

Specifies that the RACF subsystem is the processing environment of the command. The subsystem prefix can be either the installation-defined prefix for RACF (1 - 8 characters) or, if no prefix has been defined, the RACF subsystem name followed by a blank. If the command prefix was registered with CPF, you can use the MVS™ command D OPDATA to display it or you can contact your RACF security administrator.

Only specify the subsystem prefix when issuing this command as a RACF operator command. The subsystem prefix is required when issuing RACF operator commands.

group-name

Specifies the name of the group whose profile is to be added to the RACF database. If you are defining more than one group, the list of group names must be enclosed in parentheses.

This operand is required and must be the first operand following ADDGROUP. Each group-name must be unique and must not currently exist in the RACF database as a group name or a user ID.

AT | ONLYAT

The AT and ONLYAT keywords are only valid when the command is issued as a RACF TSO command.

AT([node].userid ...)

Specifies that the command is to be directed to the node specified by node, where it runs under the authority of the user specified by userid in the RACF subsystem address space.

If node is not specified, the command is directed to the local node.

ONLYAT([node].userid ...)

Specifies that the command is to be directed only to the node specified by node where it runs under the authority of the user specified by userid in the RACF subsystem address space.

If node is not specified, the command is directed only to the local node.

CSDATA

Specifies information to add a custom field for this group.

Usage for each custom field is defined using the CFDEF operand of the RDEFINE command for resource profiles in the CFIELD class. Contact your security administrator to see how custom fields are used at your installation. For more information about custom fields, see z/OS Security Server RACF Security Administrator's Guide.

custom-field-name(custom-field-value) ...

Specifies the name and value of a custom field for this group. You can add values for multiple custom field values with a single ADDGROUP command.

Rules:

• You must use the same custom-field-name as defined by the CFIELD profile named GROUP.CSDATA.custom-field-name. (The CFIELD profile is defined using the CFDEF operand of the RDEFINE command.)
• You must specify a custom-field-value that is valid for the attributes of this custom field. (The attributes, such as data type, are defined in the CFDEF segment of the CFIELD profile.)

DATA('installation-defined-data')

Specifies up to 255 characters of installation-defined data to be stored in the group profile and must be enclosed in single quotation marks. It might also contain double-byte character set (DBCS) data.

Use the LISTGRP command to list this information.

DFP

Specifies that when you define a group to RACF, you can enter any of the following suboperands to specify default values for the DFP data, management, and storage classes. DFP uses this information to determine data management and DASD storage characteristics when a user creates a new group data set.

DATAAPPL(application-name)

Specifies DFP data application identifier. The maximum length of a data class name is 8 characters.

DATACLAS(data-class-name)

Specifies the default data class. The maximum length of a data class name is 8 characters.

A data class can specify some or all of the physical data set attributes associated with a new data set. During new data set allocation, data management uses the value you specify as a default unless it is preempted by a higher priority default, or overridden in some other way (for example, by JCL).

Note: The value you specify must be a valid data class name defined for use on your system. For more information, see z/OS Security Server RACF Security Administrator's Guide.

For information on defining DFP data classes, see z/OS DFSMSdfp Storage Administration.

MGMTCLAS(management-class-name)

Specifies the default management class. The maximum length of a management class name is 8 characters.

A management class contains a collection of management policies that apply to data sets. Data management uses the value you specify as a default unless it is preempted by a higher priority default, or overridden in some other way (for example, by JCL).

Note: The value you specify must be defined as a profile in the MGMTCLAS general resource class, and the group must be granted at least READ access to the profile. Otherwise, RACF does not allow the group access to the specified MGMTCLAS. For more information, see z/OS Security Server RACF Security Administrator's Guide.

For information on defining DFP management classes, see z/OS DFSMSdfp Storage Administration.

STORCLAS(storage-class-name)

Specifies the default storage class. The maximum length of a storage-class-name is 8 characters.

A storage class specifies the service level (performance and availability) for data sets managed by the Storage Management Subsystem (SMS). During new data set allocation, data management uses the value you specify as a default unless it is preempted by a higher priority default, or overridden in some other way (for example, by JCL).

Note: The value you specify must be defined as a profile in the STORCLAS general resource class, and the group must be granted at least READ access to the profile. Otherwise, RACF does not allow the group access to the specified STORCLAS. For more information, see z/OS Security Server RACF Security Administrator's Guide.

For information on defining DFP storage classes, see z/OS DFSMSdfp Storage Administration.

MODEL(dsname)

Specifies the name of a discrete MVS data set profile to be used as a model for new group-name data sets. For this operand to be effective, the MODEL(GROUP) option (specified on the SETROPTS command) must be active.

RACF always prefixes the data set name with group-name when it accesses the model.

For information about automatic profile modeling, refer to z/OS Security Server RACF Security Administrator's Guide.

OMVS

Specifies z/OS UNIX System Services information for the group being defined to RACF.

AUTOGID | GID

Specifies whether RACF is to automatically assign an unused GID value to the group or if a specific GID value is to be assigned.

AUTOGID

Specifies that RACF is to automatically assign an unused GID value to the group. The GID value is derived from information obtained from the BPX.NEXT.USER profile in the FACILITY class. For more information on setting up BPX.NEXT.USER, see z/OS Security Server RACF Security Administrator's Guide.

If you are using RRSF automatic command direction for the GROUP class, the command sent to other nodes will contain an explicit assignment of the GID value which was derived by RACF on the local node.

Rules:

• AUTOGID cannot be specified if more than one group is entered.
• The AUTOGID keyword is mutually exclusive with the SHARED keyword.
• If both GID and AUTOGID are specified, AUTOGID is ignored.
• Field-level access checking for the GID field applies when using AUTOGID.

GID(group-identifier) [SHARED]

GID(group-identifier)

Specifies the group identifier. The GID is a numeric value from 0 - 2 147 483 647.

When a GID is assigned to a group, all users connected to that group who have a user identifier (UID) in their user profile can use functions such as the TSO/E command, OMVS, and can access z/OS UNIX files based on the GID and UID values assigned.

Rules:

• If the security administrator has defined the SHARED.IDS profile in the UNIXPRIV class, the GID must be unique. Use the SHARED keyword in addition to GID to assign a value that is already in use.
• If SHARED.IDS is not defined, RACF does not require the GID to be unique. The same value can be assigned to multiple groups, but this is not recommended because individual group control would be lost. However, if you want a set of groups to have exactly the same access to z/OS UNIX resources, you might decide to assign the same GID to more than one group.
• RACF allows you to define and connect a user to more than 300 (which is the same as the NGROUPS_MAX variable defined in the POSIX standard) groups, but when a process is created or z/OS UNIX group information is requested, only up to the first 300 z/OS UNIX groups are associated with the process or user.

  The first 300 z/OS UNIX groups, that have GIDs, to which a user is connected are used by z/OS UNIX. LISTUSER displays the groups in the order that RACF examines them when determining which of the user's groups are z/OS UNIX groups.

  See z/OS UNIX System Services Planning for information on NGROUPS_MAX.

SHARED

If the security administrator has chosen to control the use of shared GIDs, this keyword must be used in addition to the GID keyword to specify the group identifier if it is already in use by at least one other group. The administrator controls shared GIDs by defining the SHARED.IDS profile in the UNIXPRIV class.

Rules:

• If the SHARED.IDS profile is not defined, SHARED is ignored.
• If SHARED is specified in the absence of GID, it is ignored.
• If the SHARED.IDS profile is defined and SHARED is specified, but the value specified with GID is not currently in use, SHARED is ignored and UNIXPRIV authority is not required.
• Field-level access checking for the GID field applies when using SHARED.
• The SHARED keyword is mutually exclusive with the AUTOGID keyword.

OVM

Specifies OpenExtensions VM information for the group being defined to RACF.

GID(group-identifier)

Specifies the OpenExtensions VM group identifier. The GID is a numeric value from 0 - 2 147 483 647.

If you do not specify GID, the group is assigned the default GID of 4294967295 (X'FFFFFFFF') and a LISTGRP shows NONE for the GID.

Note:

1. RACF does not require the GID to be unique. The same value can be assigned to multiple groups, but this is not recommended because individual group control would be lost. However, if you want a set of groups to have exactly the same access to the OpenExtensions VM resources, you might decide to assign the same GID to more than one group.
2. The value defined for the NGROUPS_MAX variable in the ICHNGMAX macro on VM defines the maximum number of OpenExtensions VM groups to be associated with an OpenExtensions VM process or user. The NGROUPS_MAX variable on VM is a number from 32 - 125, inclusive. However, RACF allows you to define and connect a user to more than the number of groups defined in this variable. If the NGROUPS_MAX variable is n and a process is created or OpenExtensions VM group information is requested, only up to the first n OpenExtensions VM groups are associated with the process or user. The first n OpenExtensions VM groups to which a user is connected are used by OpenExtensions VM. LISTUSER displays the groups in the order that RACF examines them when determining which of the user's groups are OpenExtensions VM groups.

   See z/OS Security Server RACF Macros and Interfaces for information on NGROUPS_MAX.

OWNER(userid or group-name)

Specifies a RACF-defined user or group to be assigned as the owner of the new group. If you do not specify an owner, you are defined as the owner of the group. If you specify a group name, it must be the name of the superior group for the group you are adding.

SUPGROUP(group-name)

Specifies the name of an existing RACF-defined group. This group becomes the superior group of the group profile you are defining.

If you omit SUPGROUP, RACF uses your current connect group as the superior group.

If you specify a group name and also specify OWNER with a group name, you must use the same group name on both SUPGROUP and OWNER.

If your authority to issue ADDGROUP comes from the group-SPECIAL attribute, any group you specify must be within the scope of the group in which you are a group-SPECIAL user.

TERMUACC | NOTERMUACC

TERMUACC

Specifies that during terminal authorization checking, RACF allows any user in the group access to a terminal based on the universal access authority for that terminal. TERMUACC is the default value if you omit both TERMUACC and NOTERMUACC.

NOTERMUACC

Specifies that the group or a user connected to the group must be explicitly authorized (through the PERMIT command with at least READ authority) to access a terminal.

TME

Specifies that information for the Tivoli® Security Management Application is to be added.

Note: The TME segment fields are intended to be updated only by the Tivoli Security Management Application, which manages updates, permissions, and cross references. A security administrator should only directly update Tivoli Security Management fields on an exception basis.

ROLES(profile-name ...)

Specifies a list of roles that reference this group.

The profile-name value should be the name of a defined role, which is a discrete general resource profile in the ROLE class.

UNIVERSAL

Specifies that this is a universal group that allows an effectively unlimited number of users to be connected to it for the purpose of resource access. The number of users in a universal group with authority higher than USE, or with the attributes SPECIAL, OPERATIONS or AUDITOR at the group level, is still limited to 5957.

When displayed with the LISTGRP command, not all group members will be listed. Only users with authority higher than USE or with the attributes SPECIAL, OPERATIONS or AUDITOR at the group level will be shown in the member list.