Release Overview

Universal Agent Release 6.9.0.0 is considered an interim Release to prepare the ground for a central license and Audit Management System, Universal Controller for Agent Management (UCAM). UCAM allows customers to centrally apply and audit license keys for all Universal Agent components in one place using a single GUI for all administrative purposes regarding license keys. It currently is limited to license management functionality but will be enhanced in upcoming releases to a full function Agent Management System.

An Agent-only client can optionally decide to implement UCAM and connect the Universal Agent environment centrally, via UAG/OMS, to UCAM to take advantage of the single license key approach.

For all pre-6.9.0.0 Universal Agents (except Tandem and I-Series) that are still under support, the existing local licensing will continue to operate as usual.

Changing to UCAM will require additional components to be available for supporting central license management.

For detailed information on UCAM installation and set-up, see Universal Controller for Agent Management.

Note

UCAM can be downloaded from the Universal Agent / Universal Data Mover section of Software Downloads in the Stonebranch Customer Portal.

Release Notes

Universal Agent release 6.9 contains the following high level features. For a complete list of all included features and fixes, please refer to the Universal Agent 6.9.x Maintenance list.

Application Integration

Backlog ID

Title

Description

B-10715

UA Python - Add External Module to Packaged Delivery

The following list of Python Modules and their respective Versions, used by Stonebranch-created Universal Task/Template definitions, will be included within the Python package delivered alongside Universal Agent. They do not require any further installation effort once the Agent has been installed.

Module Name	Version
azure-storage-blob	12.1.0
azure-storage-logging	0.5.1
botocore	1.14.8
boto3	1.11.8
docker	4.1.0
google-cloud-storage	1.25.0
paramiko	2.7.1
requests	2.22.0

No additional installation or set-up activities will be required for the Python modules listed above.

Universal Agent Architecture

Backlog ID

Title

Description

B-11181

Extend password scrubbing to CSK methods

When certain command and scripts are run with embedded user ID/password information, this information can be displayed in trace statements when message_level is set to trace.

The two trace points in question are:

20190923 101709.181894 CPR ENTRY prcattr.c 00474 00004a90 CSProcessAttribSetCommand(000001E5867903A0, echo xxxsecretxxx )
20190923 104155.555310 CPR ENTRY prcattr.c 00367 00005c08 CSProcessAttribSetScriptLine(0000018AC90E5850, echo xxxsecretxxx

With B-11181, the command and script lines in the offending trace statements will be replaced with *****.

B-12001

Universal Java networking component (used by OMS Java Client) - Modify properties referenced in code to use the new "uc." pathing initiated by the ControllerCritical

Universal Controller 6.9.0.0 modified the prefix used for properties from “opswise.” to “uc.”. The Universal Java Networking component (used by the OMS Java Client) references a subset of the Controller’s properties related to key managers and trust managers. Therefore, the Universal Java Networking Component must modify the property names it uses to the new “uc.” prefix used by the Controller.

Properties in question are

In file .\ua\autoctr-projects\universal\src\com\stonebranch\universal\net\UniversalTrustManager.java, function com.stonebranch.universal.net.UniversalKeyManager.UniversalKeyManager() was modified to reference the new property names:

uc.keymanager.algorithm
uc.keymanager.provider
uc.keymanager.client.alias

In file .\ua\autoctr-projects\universal\src\com\stonebranch\universal\net\UniversalSession.java, function com.stonebranch.universal.net.UniversalSession.sendNegotiation() was modified to reference the new property name:

opswise.trustmanager.ssl.protocols => uc.trustmanager.ssl.protocols

In file .\ua\autoctr-projects\universal\src\com\stonebranch\universal\net\UniversalTrustManager.java, function com.stonebranch.universal.net.UniversalTrustManager.UniversalTrustManager() was modified to reference the new property names:

opswise.trustmanager.algorithm => uc.trustmanager.algorithm
opswise.trustmanager.provider => uc.trustmanager.provider

z/OS Features

Backlog ID	Title	Description
B-11540	z/OS UAGSRV: Support exits issuing messages to UAG JESMSGLG, LOG and TRACE datasets	The $LOGMSG macro will allow assembler programs to issue message to the UAG LOG dataset with a severity level of INFO, DEBUG and TRACE. The appropriate log level will need to be set to allow the messages to be logged. It will allow TRACE messages with a level of ENTRY, EXIT, TRACE and WATCH. Trace will need to be active to allow the messages to be logged. For JESMSGLG messages, the message number will be 1097. The levels will be ERROR, WARN, INFO, AUDIT and TRACE. The appropriate log level will need to be set. The macro specification will allow a single text string to be sent. The assembler code line number and the issuing CSECT name will be sent as well. These will be printed in the LOG and TRACE datasets to indicate the source of the message.
B-11561	z/OS UAGSRV: Implementation bi-directional messaging between primary and secondary agents in sysplex	With Universal Agent 6.9.0.0, UAG for z/OS will create and join a Sysplex group if it is running Sysplex-aware. The XCF group name will consist of the characters UAG, followed by the first 4 (upper cased) characters of the system ID (system_id from UBRCFG00). Each UAG will have a member name, which will be the group name appended with @ and followed by the MVS system name. So, for example, my UAG with a system ID of mndv, running on DVZOS202, would have a group name of UAGMNDV and a member name of UAGMNDV@DVZOS202.
B-06132	Recognize when a pre-allocated file is updated on z/OS (Implementation) Note Universal Agent 6.9.0.0 Behavioral Change: Adding a z/OS File Monitor type "change" that may affect your current file monitor settings for z/OS.	Currently, UAG for z/OS uses SMF record type 15 to detect dataset creates. The same record can be used to detect updates. Create File Monitors will be modified to trigger only on creation of a dataset. Change File Monitors will be supported by having them trigger on dataset updates. Additionally, UAG for z/OS will start collecting SMF type 18 records. (These are created when a dataset is renamed.) When a dataset rename is detected which matches a Change File Monitor, the File Monitor will also trigger. For Change File Monitors, z/OS will support only the “Monitor File(s)” field in the “Agent File Monitor Details” section of the “Agent File Monitor” pane. Wildcards * and ? will be supported. For Create File Monitors, z/OS will continue to support only the “Monitor File(s)” field in the “Agent File Monitor Details” section of the “Agent File Monitor” pane. Wildcards * and ? are supported. Both Create and Change File Monitors will not be triggered until a dataset has been opened for output and then subsequently closed. Change File Monitors will also trigger when a rename of a dataset completes successfully.
B-10813	Suppress ICH408I message for unprivileged z/OS Agent install	Running UDM with an un-authorized User message ICH408I USER(UBRTRP ) GROUP(UBRGRP ) NAME(####################) BPX.SUPERUSER CL(FACILITY) INSUFFICIENT ACCESS AUTHORITY ACCESS INTENT(READ ) ACCESS ALLOWED(NONE ) is shown within the LOG. Even though it is an informational message confirming that the user does not have authorization, it is often considered as a "security issue" in Audits. To avoid confusion, the RACF-check, leading to thai message, will be ommited when an unauthorized user is used.

Hybrid IT/Cloud

Backlog ID

Title

Description

B-11915

Make all Universal Agent DNS alias comparisons case-insensitive

A customer has identified a situation in which a Universal Agent’s Access Control List (ACL) entry will not be applied if the host name portion of the entry does not match a resolved host name returned by a domain name server (DNS).

According to RFC-4343, resolved host names returned from a DNS should be compared in a case-insensitive manner.

The Universal Agent logic that selects ACL entries by comparing host names is currently doing a case-sensitive comparison. This means that entries that should be applied for a particular host will be bypassed, mistakenly allowing or denying access to UA components.

To conform to RFC-4343, any host names compared during ACL entry processing will be treated in a case-insensitive manner.

B-11408

Expose Agent external/NAT IP

Since the client is not aware of its external IP, it cannot report that to the Controller in the JSS-HELLO message. However, the external IP is known by the OMS server when a client connects. What was missing is the way to report that IP from the OMS server to the Controller.

However, OMS Server already has notification messages for client connection connection open/close events. The connection open event (destination=topic.oms.event.connection.open) already contains the “clientid” tag which carries the client’s queue name in the “ops.agent.AGENTID” format.

The new tag “clientip” was added into the event. Its value contains the IP address of the source of client connection to the OMS server. That value is the external IP of a client if it resides behind NAT.

New Central Licensing: UCAM

Backlog ID

Title

Description

B-10873

UAG sending License Information to Ubroker

Ensure proper license processing for Universal Broker working for a pre-Universal Agent 6.9.0.0 environment and map local license keys, as defined in UCMD and UDM Manager components to the new license structure.

This is mainly to avoid unnecessary communication between a Broker and the central license managemnt component. Once the Broker has received / Aquired the License key it will handle further license requirements locall on the Broker level.

B-10874

Start-up sequencing between Primary and Secondary z/OS UAGs

When a Primary agent starts, it will initialize normally (Like a non-Sysplex UAG). Additionally, it will broadcast an (internal) XCF message to all members connected to the UAG Sysplex Group. (A group that encompasses all Primary and Secondary agents in the Sysplex that share the same system_id value.) When a Secondary agent receives this message, it will reply to it. Once the Primary agent receives a reply, it will send another XCF message to the replying Secondary agent containing its license information. The Secondary agent will use this information to decide to start processing, or shut down.

When a Secondary agent starts, it will initialize to the point where it can start to process. It will remain in a state where no tracking data of any kind will be processed. It will wait to be contacted by a Primary agent.

Tracking data will be collected by the various UAG exits and cached in the high common storage area while there is space. (The size of this area is defined by the high_common_storage configuration parameter.) Jobs will continue to run and UAGRERUN will function normally. However, job tracking, File Monitor and Syslog message information will not be processed until the Secondary receives a valid license.

If a Primary shuts down after granting licenses to Secondary agents, all Secondary agents will return to their initial state, waiting to be contacted by the Primary. Secondaries will have to re-acquire a license when the Primary restarts. If the number of licenses has been reduced for any reason (or the number of Secondaries increased), some Secondaries will not receive a new license and will have to stop processing.

Licenses are handed out by the Primary on a first come, first serve basis.

In case a Secondary agent starts after the Primary agent, the Primary agent will detect the startup and broadcast the same XCF message it broadcast on startup. Processing will then proceed as described above. (Agents can detect the startup, and shutdown, of any agent in their group through XCF events that are sent to all agents connected to the group.)

Note

When upgrading in a Sysplex environment, the customer should upgrade the Primary first and then the Secondaries (or upgrade them all at the same time).

If the Secondaries are upgraded first, and then the Primary, the Secondaries will not initialize because they will be waiting for a V6.9.0 Primary to contact them.

B-11515

Ubroker receives UAG license Information

Implementation allows Ubroker to receive the new license information in the new MSID_BROKER_LICENSE command from the broker interface IPC.

Message issued upon reception of license Information:

UNV0226I [1000000001] License Information Received: EXPIREDATE 0, DISTRIBUTED 0, ZOS 0, ZOSSECONDARY 0, USAP 0, UPPS 0, SOA 0

When GA, the above message will contain the details of the license key received.

B-11518

Distribute License key, to UAC (SOA conector) when needed

The UNiversal Agent 6.9.0.0 release removes the requirement to enforce licenses based on endpoint counts.

License enforcement is based solely on the following supported protocols:

HTTP
JMS
SOAP
XD SOAP
IBM WebSphere MQ

A value of TRUE authorizes the protocol for use; a value of FALSE prohibits use of the protocol.

The JMS, SOAP, and MQ protocols control inbound (file listener) and outbound (Web service execution) connections. If the protocol is licensed, the SOA connector is authorized to create an unlimited number of inbound or outbound connections using that protocol.

The SOA connector uses the HTTP and XD SOAP for Web service execution only.

A 6.9.0.0 Universal Agent receives license information upon receipt of a UC 6.9.0.0’s HELLO message response
The Universal Broker receives the license information from UAG Server
The Universal Broker forwards the license information to UAC Server during component registration.

When UAC Server starts, it may perform component registration before the Broker has obtained license information from the Controller. In this case, the license is un-acquired at this point and UAC Server terminates.
The UAC Server component definition may be authored to restart until it either:
- Receives license information.
- Exceeds the number of retry attempts.

UAC Server starts a local Apache Tomcat container and starts an application to execute within that container
- This application is responsible for servicing inbound and outbound requests
- License enforcement occurs when it receives new inbound or outbound requests

B-11519

UAGSRV: Receive new license parameters in HELLO message response

The Controller handles the JSS-HELLO message from UAGSRV and sends back the license information in the JSS-HELLO response. UAGSRV collects the information for transmission to the ubroker process. Since there is no way to check the new field existence, the following log message was added to the agent.log:

"License info: CUSTOMER: <custname>, REGISTERED: YES, EXPIREDATE: <expdt>, DISTAGENTS: <cnt>, ZOSAGENTS: <cnt>, ZOSSECAGENTS: <cnt>, USAP: <conn>, UPPS: <conn>, SOA: <protocols>"

JSS-HELLO message tags containing license information

Tag	Type	Description
LICCUSTOMER	String buffer	Licensed customer name
LICEXPIREDATE	String representation of 64-bit unsigned integer	Expiration date (TBD)
LICDISTAGENTS	String representation of 32-bit unsigned integer	Number of distributed agents
LICZOSAGENTS	String representation of 32-bit unsigned integer	Number of z/OS agents
LICZOSSECAGENTS	String representation of 32-bit unsigned integer	Number of z/OS secondary agents
LICUSAP	String representation of 32-bit unsigned integer	Number of USAP connections granted by the license
LICUPPS	String representation of 32-bit unsigned integer	Number of UPPS connections granted to the agent.
LICSOA	String representation of 32-bit unsigned integer	A value that indicates which Web service protocols/endpoints the SOA connector may use/connect to, from the following: HTTP JMS SOAP XD SOAP IBM WebSphere MQ
REGISTERED	“YES”/”NO”, or “TRUE”/”FALSE”	Flag indicating whether the agent is successfully registered and the license was granted.

Recognizing a 6.9.0.0 License:

All of the new license handling implemented in the Agent requires it to know whether a new, 6.9.0.0 license was obtained from Universal Controller. If the HELLO response does not contain information for a 6.9.0.0 license, the Agent must rely on locally-configured license information.

If the Agent does not receive values for the REGISTERED, LICEXPIREDATE, LICDISTAGENTS, and LICZOSAGENTS parameters, then it will behave as though it received a HELLO response from a pre-6.9.0.0 Controller and local license information is used.

B-11543

Enforce startup order of autostart components so that OMS & UAG start first

Starting with Universal Agent 6.9.0.0, all licensing can, optionally, be handled by Universal Controller for Agent Management

Prior to 6.9.0.0 licenses for individual agent components were stored in their respective configuration files. Aside from verifying that the license information was valid (i.e., the individual license parameters were capable of generating a key at runtime that matched the configured license key)

To ensure proper startup behavior, the UA components responsible to obtaining license information (manager components) from the Controller must be started in an orderly fashion.

Specifically, an OMS Server must exist to enable message exchange between the Central license management and Agent. OMS Server does not need to run on every Agent installation, but it must start first for those agents that do have it set to auto start.

Next, a UAG Server must start to register with the Controller and receive the license information. All agents must now execute a UAG Server that connects to an OMS Server (B-11845), and that UAG Server must start before the Broker can proceed with its startup.

After OMS Server (if necessary) and UAG Server start – and valid license information is available to the Universal Broker – the order in which the Broker starts remaining auto-start components is not important.

B-11544

Ensure that Universal Broker does not open any local Service Interfaces until license Information is received

At this stage the license received from the Controller by UAG and passed to the Broker. The Broker saves the information and allows the UCMD/UDM component startup only in case if the license was received and the agent is allowed to execute jobs. Also, the current license information on the broker side is available for display in the UQUERY output.

In case if UAG did not pass the license to the Controller for any reason (UAG is not connected to OMS, Controller unavailable, etc), the broker will refuse to start UDM or UCMD component with the following error:

UNV3354E [1000000001] Error starting component ucmd for client 127.0.0.1:61830: CPMStartComponent, 25, License for running this component was not acquired

2020.06.24 15.48.45.455 UNV3385W [1000000001] Manager component ucmd 1593002837 (PID20045) ended with non-zero exit code 202 (000000CA).

B-11546

Universal Broker to refresh local license Info with UCTRL

The Universal Control (UCTL) utility must not cause Universal Controller-obtained license information that is cached within Universal Broker to be replaced with locally-configured license information during a configuration refresh.

The Universal Broker is responsible for responding to a UCTL configuration refresh request (i.e., UCTL -refresh). In its response handling, the Broker re-reads all configuration files and stores the information in its cached configuration information. When this occurs, it is not possible to prevent the Broker from re-reading and re-caching any locally-configured license information that may exist in the configuration files. However, it is possible – and necessary – to prevent the re-cached license information from being applied and enforced against license information obtained from Universal Controller.

To enforce the requirement, the Broker must cache license information separately from the configuration file cache. The Broker must know the source of the license information in that separate cache. Finally, the Broker must know when license acquisition is complete, and the source of the license information to enforce is resolved.

At startup, the Universal Broker always caches any locally-configured license information and maps that information to the new license parameters. This new licensing information is stored in a cache that is separate from the cache used for local configuration files.

At the point where license information is merely mapped and cached, the Broker considers the license to be un-acquired (i.e., the license’s source has not been fully resolved). The Broker knows it has cached local license information, but won’t enforce that information until license acquisition completes.

The Universal Broker will allow any cached, locally-configured license information to be refreshed while the license is un-acquired.

The idea behind this implementation is to ensure no stale data exists when the Broker resolves the license source to use locally-configured information.

If the Broker completes license acquisition and determines that locally-configured license information should be used, that Broker will allow that information to be refreshed at any time and it will enforce the refreshed information.

If, at any point during its life, the Broker receives notification that UAG Server successfully connected to Universal Controller and received a 6.9.0.0 or later license, only that remote license information will be used. To prevent a UCTL refresh from overlaying this information, the Broker changes the license source from local to remote. The function within the Broker that handles the license configuration refresh sees that a remote license is being used and will immediately exit. This ensures that after a remote license is acquired, the Broker never allows a UCTL refresh to update the cached license information again.

There is no situation in which a Broker will “fall-back” to using locally-configured license information after it acquires a UC 6.9.0.0 or later license.

No combination of UCTL refreshes or UAG Server activity will allow remote license information to be replaced with local information.

B-11552

Implementation USAP licensing based on results of B-11521

Special Handling for USAP/UPPS Licensing

Licensed execution of the Universal Connector for SAP (USAP) and Universal Connector for PeopleSoft Process Scheduler (UPPS) will be enforced using a value that represents the number of concurrent connections any USAP or UPPS component executing on behalf of a licensed agent may use at one time.

Every agent as of UA 6.9.0.0, that connects to a Universal Controller 6.9.0.0 or later will receive the SAP and PeopleSoft connections that are included with the Controller’s license.

The UAG Server is responsible for providing this information to its Universal Broker, which is then responsible for providing the values to the USAP and UPPS components.

USAP and UPPS are responsible for defining what constitutes a unique connection.

USAP and UPPS are responsible for ensuring that the number of unique connections in use at any given time do not exceed the value provided by the license.

Sample

Suppose that a customer purchases a license that permits 5 SAP connections.

This customer has 2 6.9.0.0 Universal Agents.

Each agent will receive this value (5). A USAP instance running on either agent will be permitted to use 5 unique SAP connections at the same time. An attempt to create a 6th unique connection while the other 5 are in use will fail.

B-11551

Implementation UPPS licensing based on results of B-11520

Legacy licenses did not allow to limit the connections number made by upps, i.e. the number was unlimited. The new license sends the maximum connections allowed by the license to the broker, which must keep track of all active connections and allow/reject any new connections depending on how many connections are currently active.

A “connection” for UPPS is defined as the PeopleSoft Connector’s Endpoint .

The license restricts the number of simultaneous unique connections performed by UPPS, meaning that the numer of sessions to the same PeopleSoft Endpoint is unlimited.

B-11553

Implement USOA licensing depending on results of B-11522

The Universal Connector for SOA (USOA) is an optional agent component that executes Web services using one of the five connection protocols or endpoints:

HTTP
JMS
SOAP
XD SOAP
IBM WebSphere MQ

All that USOA needs to know is whether or not the customer purchased a license that permits Web service execution using one of the supported protocols/endpoints.

Because there is no requirement for the agent to request any USOA-specific license information from the Controller, no updates to the HELLO message are needed to support USOA’s new licensing implementation.

The protocols/endpoints the customer is permitted to execute will be sent via parameters in the HELLO message response. The Universal Broker will forward the value of these parameters to USOA, which is responsible for managing Web service execution based on the values it receives.

B-11917

Universal Broker to check license expiration once a day

A 6.9.0.0 Universal Agent receives license information upon receipt of a UC 6.9.0.0’s HELLO message response

The Universal Broker receives the license information from UAG Server

The Universal Broker converts the expiration date to local time.

Universal Controller licenses expire at 23:59:59 UTC

The first expiration check occurs at this time, converted to local time.

After the first expiration check, subsequent checks occur at 24 hour intervals.

Expiration notices begin 30 days prior to the expiration date.

The Universal Broker sends the expiration date to licensed components upon local registration.

Each licensed component will report an expired license at startup.

When a 6.9.0.0 Universal Agent (UA) connects to a 6.9.0.0 UACM(via UAG Server and OMS) it will receive license information during the HELLO message/response exchange that occurs at UAG Server startup. UC has always maintained its own license information, but in 6.9.0.0 the information it maintains is expanded to control UA licensing. This single set of license information allows the Agent to manage licensing for all of its components and eliminates the need to have licenses stored in local configuration files.

UA receives a single license expiration date from the Controller and applies that expiration date to all licensed components. Although UAG Server is the direct recipient of this license information the Universal Broker is the final keeper of it, given its traditional role as owner of an agent’s local configuration.

As a long-running process, the Universal Broker must implement a daily check on the license’s expiration date. Starting 30 days prior to a license’s expiration, the Broker will issue the following message when it performs its periodic check on the license:

UNV0130W [] Product license expires in nn day(s). Contact Stonebranch, Inc. for license renewal.

Individual licensed components will also display this message at startup.

When the expiration date elapses, the Broker must ensure that no new work can start on that Universal Agent instance. The Broker and any auto-started components will continue to run, but will fail upon a check of the license’s expiration date.

When a license expires, you can expect to see the following message in the Broker log and from licensed components:

UNV0129E [] License is expired. Contact Stonebranch, Inc. for license renewal.

Expired licenses can still be considered to be valid. Validity and expiration are handled and reported differently.

Universal Agents that connect to Universal Controller whose license is expired will still receive a HELLO response. The Agent will be granted the license, provided the number of licensed agents is not exceeded.

Universal Agents do not change state when a UACM license expires. Any “online” Agents will continue to show online after the license expires.

However, when a UCAM license expires, it will enter a paused state, which will prevent any Universal Agent task execution. After a new license is applied, you must select the UACM Server Operations option and execute the Resume Cluster Node task.

Browser not supported