Currently, Universal Agent 7.8.0 for IBM i does not include Universal Command (UCMD) or Universal Data Mover (UDM). Customers who require those components should use an older version of Workload Automation for IBM i. The latest version containing those components is 5.1.1. Older versions of Workload Automation for IBM i can be installed alongside version 7.8.0.

Objective

This page provides installation requirements and summary for Universal Agent 7.8.0 on an IBM i system.

System Requirements

The requirements for installation of Universal Agent for IBM i are:

IBM i V7R3M0 or above.
TCP/IP.
User profile with *ALLOBJ, *SPLCTL, *JOBCTL, and *SECADM authorities.
About 360 megabytes of disk space.
Network-attached workstation.

The Universal Agent 7.8.0 for IBM i installation process creates a product user profile, UNVUBR770, that is given *ALLOBJ special authority. UNVUBR770, with *ALLOBJ special authority, is required to successfully complete the installation.

Note

Some organizations and companies require the removal of *ALLOBJ authority from non-administrative user profiles. Universal Agent may be configured to run without *ALLOBJ authority; however, to do so requires additional administrative overhead. The steps required to remove product *ALLOBJ authority are described in Universal Broker Security.

The *BASE option contains the complete installation. This includes all of the components and utilities listed above.

Platform Requirements

Since platform requirements may change with new releases of a product, please consult the /wiki/spaces/Staging/pages/1505918977 page to make sure that your platform is supported before performing an installation.

Libraries and Logs

Under the IBM i native file system, Universal Agent write to product files residing in various libraries and write information to job logs.

This section specifies the following information for various libraries and logs:

Estimated amount of space required
Required security access
Location of the production files

Universal Broker Job Log

Under IBM i, Universal Broker writes its messages to the UBROKER job log.

Space

Job log file growth is dependent on use of the Universal Agent Servers. The disposition and size of the job log depends on the job definition as well as system variables QJOBMSGQMX (maximum job log size) and QJOBMSGQFL (action when job log is full).

Security

Since Universal Broker uses a normal job log, no special security is required.

Command Reference Library

Universal Command Server can execute commands of type cmdref. A command reference is a predefined command or script to which the Universal Command Manager refers by its file name.

The default command reference library name is UNVCMDREF. For security reasons, the name of this library can be changed only via the Universal Command Server configuration, located in the UNVCONF file and UCMDS member. The configuration file entry has precedence over the default value. If the name is changed to something other than the default or configured value, Universal Command Manager will no longer be able to read the command reference files; it will generate appropriate error messages if an attempt is made to do so.

Space

The amount of space is dependent solely on the number of command reference files defined.

Security

Universal Command Server requires read access to the UNVCMDREF library files. Administrator accounts require appropriate access in order to maintain the command reference files. No general user access is required.

Universal Automation Center Agent (UAG) Logging

Under IBM i, Universal Automation Center Agent (UAG) writes some messages to the job log for the UNVSRV prestart job under which it runs. However, messages are typically only sent to the UNVSRV job log in the case of unexpected errors. The primary logging destination for UAG is the /var/opt/universal/log directory in the IFS file system. The current log file is named agent.log.

Note

The agent.log files are encoded as CCSID 037, which is EBCDIC. These files can be viewed from an SSH terminal on the IBM i system, use the following command:

qsh -c "cat /var/opt/universal/uag/logs/agent.log"

The agent.log files can be viewed from the native 5250 terminal with the following command:

DSPF STMF('/var/opt/universal/uag/logs/agent.log')

Space

Job log file growth is dependent on use of the Universal Agent Servers. The disposition and size of the job log depends on the job definition as well as system variables QJOBMSGQMX (maximum job log size) and QJOBMSGQFL (action when job log is full).

Security

For the UAGSRV job log, no special security is required. However, for the primary agent log file which resides in IFS, the Universal Broker user profile (UNVUBR770) requires read/write access to the log directory and read/write access to all files in the log directory. No other Universal Agent components use the log directory at this time. No general user access is required.

Trace File Location Library

Universal Broker and its server components (for example, Universal Command Server) create product trace files when configured to do so. A trace file is used by Stonebranch, Inc. Customer Support to resolve product problems.

On IBM i, Universal Agent trace files normally are written to *CURLIB (current library). Under Universal Broker and the associated servers, the current library is the temporary library designated at installation time (UNVTMP770).

Otherwise, current library is the default current library of the user.

Space

Trace files can grow to significant size, depending on how long the trace is active and how much work the program is doing during the tracing period. Due to the information associated with IBM i pointers and fact that physical database files are fixed record lengths, trace files quickly can grow very large on a system with high Universal Broker and server activity.

If the trace file size is increased beyond 500,000 records, the maximum file size must be changed or the associated job will hang. The hang results from a system generated inquiry message, which is issued when the maximum file size is exceeded. By default, trace files wrap before reaching the maximum file size, thus avoiding the system inquiry message.

The MAX_TRACE_LINES configuration option sets the number of records at which the trace file wrapping occurs. When the maximum size is reached, the trace file will wrap to the beginning.

No space is required under normal operation for trace files. Trace files are requested by Stonebranch, Inc. Customer Support only for problem resolution. When trace files are required, at least 40MB of disk space should be available.

Security

The UNVUBR770 user profile requires at least *CHANGE authority to the UNVTMP770 library to create and use the Universal Broker and server trace files. No general user access is required.

Spool Library

The spool library is used to store the following types of information:

Execution information for Universal Agent components started by Universal Broker, UBR_CMP_DB.

Spool files are stored in the UNVSPL770 library.

Space

The spool files are located in the UNVSPL770 library. The amount of disk space required for the spool directory depends on these factors:

Whether or not activity monitoring is turned on.
The event generation configuration
The level of activity experienced by product components

Security

The UNVUBR770 user profile requires at least *CHANGE authority to the UNVSPL770 library to create and use the spool files. No general user access is required.

No other Universal Agent for IBM i components access the spool library.

UAG Cache

UAG cache is used by Universal Automation Center Agent (UAG) for storing standard I/O files.

Space

Cache files are located, by default, in directory /var/opt/universal/uag/cache.

Cache files are created for each job that is run by the Agent. They remain in the cache until they are purged by an automated purge process scheduled nightly by Universal Controller. You can configure the number of days that files remain in the cache via the Universal Controller user interface (see the Agent Cache Retention Period in Days Universal Controller system property).

The amount of disk space required for the cache directory depends on:

Number of jobs you estimate will run during the cache retention period you specified.
These files remain until they are purged by the automated cache purge process scheduled by the Controller daily at midnight.
Average size of the user processes standard output and error files.

When these numbers have been determined, the average amount of disk space is calculated with the following formula:

(RETENTION PERIOD x MAX-JOBS) x (AVERAGE-STDOUT-SIZE + AVERAGE-STDERR-SIZE) = required disk space.

For example:

If the files are purged every 7 days, and you run 1200 jobs on that agent server daily, and the average size of the STDOUT + STDERR files is 3,000 bytes, the average amount of required disk space is 25MB (7 x 1,200 x 3000).

The Universal Automation Center Agent Server automatically redirects the standard output and standard error files to the cache directory with no required user input.

Note

As with the agent.log files, UAG cache files are encoded in CCSID 037. They can be viewed using the same techniques described for Universal Automation Center Agent (UAG) Logging above.

Security

Universal Automation Center Agent requires read/write access to the UAG cache directory. No other Universal Agent components access the cache directory. No general user access is required.

UAG Extension Directory

UAG extension directory is used by Universal Automation Center Agent (UAG) for storing deployed Universal Extensions.

Space

Extension files are located, by default, in directory /var/opt/universal/uag/extensions.

Extension files are created when the Universal Controller deploys a Universal Extension to the agent. Extension deployment can occur preemptively during agent registration, or on demand during task submission. You can configure extension deployment with the following options:

The amount of disk space required for the extension directory depends on:

Number of extensions you estimate will be deployed to the agent.
Average size of the extensions.
These files remain until they are manually purged.
Only one extension deployment is required for all tasks of that type.

When these numbers have been determined, the average amount of disk space is calculated with the following formula:

(MAX-EXTENSIONS) x (AVERAGE-EXTENSION-SIZE) = required disk space.

For example:

If you expect to deploy 10 different extension types, and the average size of an extension is 1MB, the average amount of required disk space is 10MB (10 x 1).

The Universal Automation Center Agent Server automatically synchronizes deployed extensions with the version currently installed in the Controller with no required user actions.

Security

Universal Automation Center Agent requires read/write access to the UAG extension directory. Any user executing extension tasks must have read access to the extension directory.

Installation Summary

Warning

This installation procedure is intended only for default installations into simple environments. Installing into high availability environments may require a customized installation. For customized installation, parallel installation or multiple system roll out see the Installation Guide for IBM i.

Step 1	Download the distribution file from the Stonebranch Customer Portal to a computer running a supported version of Windows or UNIX.
Step 2	Extract the Licensed Program Save File from the distribution file.
Step 3	If transferring the installation file to the native, QSYS file system, create a save file, UNV770, on the target IBM I system in library QGPL. This step is not necessary if transferring the file to the IFS.
Step 4	FTP the Licensed Program Save File to either the save file created in step 1 or to /QSYS.LIB/QGPL.LIB/UNV770.SAVF.
Step 5	Execute the following command to install Universal Agent 7.8.0 for IBM i to the default libraries: RSTLICPGM LICPGM(0UNV770) DEV(SAVF) SAVF(QGPL/UNV770) Add the `FRCOBJCVN`* parameter when installing on a version of IBM i that is greater than the version identified in the distribution file. For example, when using the 7.3-targeted distribution file to install on IBM i 7.5, enter: RSTLICPGM LICPGM(0UNV770) DEV(SAVF) SAVF(QGPL/UNV770) FRCOBJCVN(YES *ALL)
Step 6	Verify the correctness of the install by executing the following command: CHKPRDOPT OUNV770
Step 7	Optionally, rename the UNVUBR770 subsystem to UBROKER for consistent operation across future installations.

Customization

Customization consists of editing configuration members in the UNVPRD770/UNVCONF source file.

Browser not supported