z/OS Installation - Converting STC User Profiles to a Non-Zero UID

Owned by Stonebranch (Deactivated)
Last updated: Feb 01, 2024

Overview

Prior to Stonebranch Solutions 4.2.0, the Universal Broker and Universal Enterprise Controller (UEC) started task user profiles were required to have an OMVS UID value of 0. As of 4.2.0, the products were enhanced to execute with a user profile defined with a non-zero UID value to improve upon the product security features.

A Universal Agent installation that already has a user profile with UID 0 in use can convert the user profile from UID 0 to a non-zero UID value. There are a number of concerns when changing a user profiles UID value. The UID value identifies the user profile in the z/OS UNIX (USS) environment.

The following sections describe how to convert a Universal Broker or Universal Enterprise Controller user profile UID value from 0 to non-zero.

Converting Universal Broker User Profile to Non-Zero UID

The conversion steps assume the following:

  • The UID value is being changed from 0 to 5001. If a UID value of 5001 does not work in your local environment, change all references to 5001 in the following steps to a unique, non-zero UID value suitable for your local environment. Note that the UID value must be unique among all user profiles.
  • The Universal Broker user profile name is UBRUSR. If the Universal Broker STC in your local environment uses a different user profile name, change all references to UBRUSR in the following steps to the user profile name used in your local environment.
  • The user ID used to execute the commands requires an OMVS segment.
  • For full feature support, the user ID must have either UID 0 or READ access to the BPX.SUPERUSER profile in the FACILITY class. Starting with Universal Agent 6.5.0.0, a majority of agent features can be accessed without READ access to the BPX.SUPERUSER and BPX.DAEMON profiles. Refer to information below and throughout this section for more information on executing without access to those profiles.
  • The Universal Broker HFS or zFS data sets must be mounted and their mount point known. The console system command D OMVS,F or the USS shell command df can be used to display all mounted USS data sets. If the Broker has never run as UID 0 or with READ access to the BPX.SUPERUSER profile, the datasets must be manually mounted with the mount locations configured and initialized as described below.
  • The external links required by Universal Broker and UDM Manager to spawn select Universal Agent components must exist in a well-known location on the z/OS UNIX file system and be owned by UID 0. The external links must be created prior to Broker startup and identified in the configuration and component definition members described below.

Step 1

Stop the Universal Broker STC if it is running.
 

Step 2

Change the user profile UBRUSR UID value to 5001 with the following command:
 

ALTUSER UBRUSR OMVS(UID(5001))

Step 3

Note

Some parts of this step are optional starting with Universal Agent 6.5.0.0. Running with access to all the profiles below is still supported in that release, but the only resource the Broker user must have READ access to is BPX.JOBNAME. Running without BPX.SUPERUSER and BPX.DAEMON access does limit the Universal Agent's feature set, but only as it applies to z/OS Unix group membership and configuring the Agent to switch user contexts without prior authentication.

 
Permit the user profile UBRUSR READ access to the required resource profiles with the following commands:
 

PE BPX.SUPERUSER CLASS(FACILITY) ID(UBRUSR) ACCESS(READ)
PE BPX.JOBNAME CLASS(FACILITY) ID(UBRUSR) ACCESS(READ)
SETR RACLIST(FACILITY) REFRESH

 
The user profile UBRUSR should already have READ access to BPX.DAEMON in the FACILITY class based on Universal Broker installation requirements prior to 4.2.0. If UBRUSR does not have READ access to BPX.DAEMON, the following commands will permit appropriate access:
 

PE BPX.DAEMON CLASS(FACILITY) ID(UBRUSR) ACCESS(READ)
SETR RACLIST(FACILITY) REFRESH

 
For detailed information regarding Universal Broker security requirements, see z/OS Configuration - Started Tasks.

Step 4

Universal Broker databases are maintained in USS HFS or zFS data sets. The database files have an owner attribute that is based on the UID value of the Universal Broker STC user profile. The database files, the root directory, and administration files must have their owner attribute changed from UID 0 to the new non-zero UID value 5001.
 
When running with UID 0 or with READ access to the BPX.SUPERUSER profile, the Universal Broker STC will dynamically mount the USS data sets in the /tmp directory. Assuming the USS data set names are UNV.UNVDB and UNV.UNVSPOOL, their mount point would be directory /tmp/UNV.UNVDB and /tmp/UNV.UNVSPOOL. If a different mount point must be used, its location can be changed with the MOUNT_POINT configuration option inside the &HLQ.UNV.UNVCONF(UBRCFG00) member. If necessary, adjust the commands below to the appropriate directory names.
 
If the Universal Broker STC has never run with UID 0 or with READ access to the BPX.SUPERUSER profile, the databases must be mounted manually as described in Universal Agent Database Configuration.
 
From the z/OS UNIX shell prompt, execute the following commands:
 

su
cd /tmp/UNV.UNVDB
chown -R 5001 *
chown 5001 .
chown 5001 .inited
cd /tmp/UNV.UNVSPOOL
chown -R 5001 *
chown 5001 .
chown 5001 .inited
exit

 
The first command, su, changes to the superuser ID. The user ID used to execute the above commands will need either a UID of 0 or READ access to the BPX.SUPERUSER profile in the FACILITY class. If the user ID has UID 0, the su command is not necessary.
 
The .inited file must exist in each directory and must be owned by the Universal Broker user. If the Broker has not run in this environment, it will be necessary to manually create this file, so its ownership can be set as instructed above. There are no content requirements for this file, so an empty file will suffice.

Step 5

Universal Broker spawns Universal Agent server components via external links that reside on the z/OS UNIX file system (USS). These links must point to names that match load modules installed into the SUNVLOAD load library.
 
UDM Manager also can spawn UCMD and USAP in response to an exec or execsap command, following the same external link approach used by Universal Broker. The Broker provides these links to UDM during registration.
 
If the Broker runs as UID 0 (or as a user with READ access to BPX.SUPERUSER), it will format and create each of these external links at start-up in the location specified by the TMP_DIRECTORY configuration option.
 
If the Broker does not run with superuser authority, each of these links must be created manually and their locations must be identified in the appropriate component definitions and configuration files.
 
To create external links for Universal Agent server components and have them recognized by Universal Broker:

  • From the z/OS UNIX shell prompt, execute the following commands:
su 
cd /tmp 
ln -e UAGSRV ubroker.stc.uagsrv 
ln -e UCMSRV ubroker.stc.ucmsrv
ln -e UCTSRV ubroker.stc.uctsrv
ln -e UDMSRV ubroker.stc.udmsrv

The directory and name (for example, ubroker.stc.uagsrv) can be any desired, but the link must point to the name of the load module in &HLQ.UNV.SUNVLOAD.

If the TMP_DIRECTORY configuration option - defined inside &HLQ.UNV.UNVCONF(UBRCFG00) - was changed from its default value of /tmp, place the external links in the location specified by the mount point value.

  • Make the following changes to the component definition files, which are stored as members inside &HLQ.UNV.UNVCOMP. If necessary, replace /tmp with the configured tmp_directory location.
    • UAGSRV: Set start_command option to /tmp/ubroker.stc.uagsrv in UAGCMP00.
    • UCMSRV: Set start_command option to /tmp/ubroker.stc.ucmsrv in UCSCMP00.
    • UCTSRV: Set the start_command option to /tmp/ubroker.stc.uctsrv in UTSCMP00.
    • UDMSRV: Set the start command option to /tmp/ubroker.stc.udmsrv in UDSCMP00.

To create external links used by UDM to execute UCMD and USAP, execute the following z/OS Unix commands
 

su
cd /tmp
ln -e UCMD ubroker.stc.ucmd
ln -e USAP ubroker.stc.usap

 
Update the UCMD_PATH and USAP_PATH Universal Broker configuration options in &HLQ.UNV.UNVCONF(UBRCFG00) to point to the absolute path of those links.
 
If you expect to stop components from Universal Broker using UCTL, create a link for it as well (for example, In -e UCTL ubroker.stc.uctl) and update the UCTL_PATH option in &HLQ.UNV.UNVCONF(UBRCFG00).
 
If you expect to launch started tasks (STCs) via UCMD using a COMMAND_TYPE value of stc or via the UDM exec stc= command, execute the following z/OS Unix commands to create an external link to the UCMD Server STC Command Processor, UCMSCPST.
 

su
cd /tmp
ln -e UCMSCPST ucmd.stc

 
Update the UCMSCPST_PATH UCMD Server configuration option in &HLQ.UNV.UNVCONF(UCSCFG00) to point to the absolute path of this new link.

Step 6

Start the Universal Broker STC.

Running Without BPX.SUPERUSER and BPX.DAEMON Access

Starting with the Universal Agent 6.5.0.0 release, running the Universal Broker STC with a user account without READ access to the BPX.SUPERUSER and BPX.DAEMON profiles enables more agent functionality than with previous releases.

The Universal Broker provided by the Universal Agent 6.5.0.0 release can execute Universal Server components (for example, UCMSRV and UDMSRV) in a specified user's context without requiring the Broker account to have access to these privileged resources. This simply requires that a valid password be provided for the user account, so that the Server component can authenticate the account.

While most agent functionality is available when executing this way, it does impose the following limitations:

  • The noauth parameter supported by some Universal Access Control List entries may not be used. This parameter is used to perform user context switches without requiring user authentication. This behavior is only available if the Broker runs with UID 0 or has BPX.SUPERUSER access.
  • Access to system resources that is granted to users via their group membership may need to be updated to specifically grant access to that user's account. Supplemental group information for the user will be set, but the process will be unable to set its effective group ID unless the user is also a member of the group to which the Broker user belongs.

In addition, the system log may contain an increased number of ICH408I messages reporting insufficient access to the BPX.SUPERUSER and BPX.DAEMON resources. This is expected behavior and is issued because some Universal Server components (UCMSRV in particular) issue a function call that checks for access to those resources. If the account requesting access does not have it, the ICH408I message is issued. Internally, the Server component continues, aware that access to the privileged resources is not available.

An ICH804I message issued by a Universal Server component may look like this:

ICH408I USER(UBRTRP  ) GROUP(UBRGRP  ) NAME(####################)
  BPX.SUPERUSER CL(FACILITY)                                     
  INSUFFICIENT ACCESS AUTHORITY                                  
  ACCESS INTENT(READ   )  ACCESS ALLOWED(NONE   )

In this instance, the Broker was running with account UBRTRP, which does not have READ access to the BPX.SUEPRUSER resource of the FACILITY RACF class.

Before attempting to run the Universal Broker STC without access to these privileged resources, be sure to follow the manual configuration steps listed in #Converting Universal Broker User Profile to Non-Zero UID.

Converting Universal Enterprise Controller (UEC) User Profile to Non-Zero UID

The conversion steps assume the following:

  • The UID value is being changed from 0 to 5002. If a UID value of 5002 does not work in your local environment, change all references to 5002 in the following steps to a unique, non-zero UID value suitable for your local environment. Note that the UID value must be unique among all user profiles.
  • The UEC user profile name is UECUSR. If the UEC STC in your local environment uses a different user profile name, change all references to UECUSR in the following steps to the user profile name used in your local environment.
  • The user ID used to execute the commands requires an OMVS segment
  • To simplify database mounting, the user ID must have either UID 0 or READ access to the BPX.SUPERUSER profile in the FACILITY class. To run without access to the BPX.SUPERUSER, simply mount, configure, and initialize databases as described in Universal Agent Database Configuration.
  • The UEC HFS or zFS data set must be mounted and its mount point known. The console system command D OMVS,F or the USS shell command df can be used to display all mounted USS data sets.


Step 1

Stop the UEC STC if it is running.
 

Step 2

Change the user profile UECUSR UID value to 5002 with the following command:
 

ALTUSER UECUSR OMVS(UID(5002))

Step 3

Optional: Permit the user profile UECUSR READ access to the required resource profiles with the following commands:
 

PE BPX.SUPERUSER CLASS(FACILITY) ID(UECUSR) ACCESS(READ)
SETR RACLIST(FACILITY) REFRESH

Step 4

UEC databases are maintained in a USS HFS or zFS data set. The database files have an owner attribute that is based on the UID value of the UEC STC user profile. The database files, the root directory, and administration files must have their owner attribute changed from UID 0 to the new non-zero UID value 5002.
 
When running with UID 0 or with READ access to the BPX.SUPERUSER profile, the Universal Enterprise Controller STC will dynamically mount the USS data set in the /tmp directory. Assuming the USS data set name is UNV.UECDB, its mount point would be directory /tmp/UNV.UECDB. If a different mount point must be used, its location can be changed with the MOUNT_POINT configuration option inside the &HLQ.UNV.UNVCONF(UECCFG00) member. If necessary, adjust the following commands to reflect the correct mount point location.
 
If the UEC STC has never run with UID 0 or with READ access to the BPX.SUPERUSER profile, the databases must be mounted manually as described in Universal Agent Database Configuration.
 
From the z/OS UNIX shell prompt, execute the following commands:
 

su
cd /tmp/UNV.UECDB
chown -R 5002 *
chown 5002 .
chown 5002 .inited
exit

 
The first command, su, changes to the superuser ID. The user ID used to execute the above commands will need either a UID of 0 or READ access to the BPX.SUPERUSER profile in the FACILITY class. If the user ID has UID 0, the su command is not necessary.
 
The .inited file must exist in each directory and must be owned by the UEC user. If the UEC STC has not run in this environment, it will be necessary to manually create this file, so its ownership can be set as instructed above. There are no content requirements for this file, so an empty file will suffice.

Step 5

Start the UEC STC.