Automic Automation - Java based Agent Guide

Products

• Automic SaaS
• CA Automic One Automation
• CA Automic Workload Automation - Automation Engine

Issue/Introduction

Agent Launcher (.exe) Architecture and JVM Integration

The Agent launcher (the .exe / executable) is a mandatory runtime component responsible for initializing the Java-based Agent in a supported and fully functional manner. It provides JVM resolution, OS-specific integrations, and lifecycle control that cannot be replicated through direct JAR execution.

Responsibilities of the Agent Launcher

The launcher performs the following essential functions:

• JVM Resolution
  Locates and validates a suitable JVM prior to Agent startup using a defined discovery sequence.

• CAU (Centralized Agent Update) Support
  Participates directly in the CAU process by executing update-related operations before the JVM is fully initialized.

• Operating System Integration
  Implements OS-dependent functionality required for security, privilege handling, and platform-specific features. These capabilities are unavailable when the Agent is not started via the launcher.

JVM Discovery Sequence

The Agent launcher (ucxjwx6, ucxj*) determines the JVM location in the following order:

1. Explicit JVM Path (-vm Parameter)
   If a -vm argument specifying the absolute JVM path is provided, that JVM is used.

2. Bundled JRE in Agent Directory
   The launcher searches for a jre directory in the Agent bin directory (including symbolic links).The Agent must be started using relative paths to ensure correct resolution:

   cd agent_bin
./ucxjlx6
    
3. JAVA_HOME Environment Variable
   If no local JRE is found, the launcher evaluates the JAVA_HOME variable.

4. System Java from PATH
   As a fallback, the launcher queries the system default Java installation by executing:

   java -XshowSettings:properties -version

   If the output contains a java.home entry, it is used as the JVM home directory.

Agent Startup and JAR Invocation

After resolving the JVM, the launcher:

• Initializes the required runtime environment (for example, CLASSPATH)

• Invokes the Agent JAR using JNI methods, equivalent to standard java.exe behavior

This startup mechanism ensures correct OS integration, security context establishment, and lifecycle management.

Unsupported Startup Scenarios

Starting the Agent without the launcher (for example, by invoking the JAR directly) results in incomplete functionality. The following features are not supported:

• CAU updates

• Windows-specific functionality, including desktop assignment and security integrations
  (Jobs may fail with runtime exceptions.)

• Unix-specific functionality, such as SUID recognition and privilege-sensitive operations

Passing Java Runtime Parameters via the Agent Launcher

After resolving a suitable JVM, the Agent launcher initializes the required runtime environment (including variables such as CLASSPATH and LD_LIBRARY_PATH), creates a runtime copy of ucxjoss.jar as ucxjoss_run.jar, and invokes the Agent’s main entry point. The launcher interprets only a small, fixed set of reserved launcher parameters (for example, -i and -v); all remaining arguments are forwarded verbatim to the JVM. This includes standard Java runtime options such as -X* memory settings and -D system properties. As a result, JVM parameters can be supplied via the Agent launcher exactly as they would be when using the native Java launcher (java.exe), with no special ordering constraints, transformation, or additional handling required.

Resolution

Architectural Changes

Design Objective

The Java Agent architecture is based on a single, shared codebase across all supported operating systems, replacing the previous model of maintaining platform-specific Agent implementations. The primary objective of this approach is to improve maintainability, consistency, and cross-platform compatibility.

Architectural Scope of Change

While achieving a unified codebase introduced some technical challenges—particularly around implementing OS-level functions not natively provided by Java—the most significant architectural changes were made in the security domain.

User Context and Privilege Model Evolution

The area with the most substantial change is the user context switch mechanism, especially in Unix environments. In the legacy (native) Agent architecture, the Agent process was designed to run continuously with the highest available privileges:

• On Unix systems, the Agent ran as root

• On Windows systems, the Agent ran with elevated privileges when started via the Service Manager (running as the Local System account)

As a result, the legacy Agent always had sufficient permissions to access protected resources (for example, certificates, security directories, job reports, and other files) without additional checks or transitions.

New Security-Centric Architecture

In the new Java-based Agent architecture, this model has been intentionally changed. The Agent no longer operates with elevated privileges by default. Instead, before accessing protected resources or performing privileged operations, the Agent explicitly acquires the required permissions based on its configuration.

Key Architectural Difference

• Old Architecture:
  The Agent process was permanently privileged and could perform all privileged operations at any time.

• New Architecture:
  To reduce the impact of a potential compromise, the Agent operates with minimal privileges and performs controlled, temporary privilege elevation only when required for specific operations, as defined by Agent settings.

Architectural Changes by Platform (Security)

Scope

User context switching is supported only for OS Agents. The implementation differs by platform due to fundamental differences in the underlying operating system security models.

Windows Agent

Security Model and Context Switching

Windows supports switching the security context at the thread level, allowing multiple threads within a single process to execute tasks under different user identities. As a result, user context switching works natively on Windows, provided the Automation Engine supplies the required credentials (for example, via a LOGIN object).

Unlike Unix, Windows security relies on:

• Access Control Lists (ACLs) for file system permissions

• Security policies for privileged OS operations (such as process creation)

• User Account Control (UAC) to limit privilege usage, even for administrative users

Under UAC, a process—regardless of how it is started—may only use elevated privileges when explicitly requested and approved.

Privilege Acquisition and Logging

When the Windows Agent is started with elevated rights, it attempts to acquire the required privileges dynamically. This behavior is reflected in the Agent log, for example:

20260101/230237.833 - U02001077 Agent process started as user: 'NT AUTHORITY\SYSTEM'
20260101/230237.833 - U02001079 Agent was able to gain all required privileges.
20260101/230237.833 - U02001081 Window Station changed from 'Service-0x0-3e7$' to 'Automic-Station$'.

 

This log sequence indicates that the Agent was started as a Windows service under the NT AUTHORITY\SYSTEM account, successfully acquired all required privileges, and is running in a service-managed window station.

In contrast, the legacy Agent architecture implicitly assumed that the process was always elevated when started by the Service Manager. This distinction is particularly relevant when the Agent is started under a specific user account or launched interactively from the desktop.

Note: Java Windows Agent needs "Create Files / Write Data" permission on the temp folder

Unix Agent

Security Model and Process-Level Context Switching

On Unix platforms, user context switching applies at the process level, not at the thread level. This limitation introduces additional complexity compared to Windows and requires supporting components to enable secure privilege separation.

Supporting Binaries

user_service_pkg

The user_service_pkg binary provides a dedicated service responsible for executing I/O operations under different user identities. The User Service:

• Is started on demand

• Remains active until an inactivity timeout is reached (default: 30 minutes)

• Runs with the minimum required privileges for the requested operation

A typical Unix Agent process structure is illustrated below:

Agent process (automic)
    |
    | --> UserService (root)
    |       |
    |       |--> Job1 (user uc4)
    |       |--> Job2 (user automic)
    |       |--> Job3 (...)
    |
    | --> UserService (for user uc4)
    | --> UserService (for user automic)
    | --> UserService (...)

 

Whether and how the User Service is started depends on the Unix Agent configuration.

SUID-Based Startup Behavior

If the Agent executable has the SUID bit set, for example:

-rwsr-xr-x 1 root uc4 529984 Nov 26 19:16 ucxjlx6*

 

the Agent is initially bootstrapped as root. In this mode:

1. A root-level User Service is started

2. The Agent process then drops privileges and switches back to the invoking user

This transition is recorded in the Agent log:

U02003082 User-Service for User 'root' was started with PID: '19170'.
U02000449 Agent process changed his identity from user 'root' to user 'automic'.

 

Root-Started Agent (Without SUID)

If the Agent is started directly as root without using SUID, the process structure is simplified. The Agent remains privileged, and User Services are started only when operations under a different user context are required:

Agent process (root)

    |
    |--> Job1 (user uc4)
    |--> Job2 (user automic)
    |--> Job3 (...)
    |
    |--> UserService (for user uc4)
    |--> UserService (for user automic)
    |--> UserService (...)

This design implements privilege separation, ensuring that elevated privileges are used only when necessary.

ucexec_pkg

The ucexec_pkg binary is a job utility responsible for job execution setup, including shell selection and environment initialization. Its role is limited to job startup and does not alter job semantics.

Compatibility Statement

Aside from the security and privilege-handling changes described above, there are no intended differences in job creation or environment setup compared to earlier Agent versions. Any deviation in these areas should be treated as a defect.

Migration Checklist for Job Execution (Upgrade to V24.4)

When upgrading to V24.4, verify the following items to ensure a smooth transition and avoid runtime or environment-related issues.

JVM and Dependency Validation

Ensure that a supported JVM version and all required system dependencies are installed on the target host. This step is mandatory when the Agent is not upgraded via a CAU package that already includes a bundled JRE.

Agent Configuration and Startup

Configure and start the Agent using the recommended privilege settings:

chown root ./ucxjlx6
chmod 4755 ./ucxjlx6

These settings are required to support the new privilege separation architecture.

Environment Verification

Due to the redesigned security model, environment-related issues may not always surface immediately. As a validation step, it is strongly recommended to manually start the Agent-related binaries from the terminal to confirm that all required system libraries and dependencies (for example, libstdc++) are available. The following commands should execute without system-level errors:

./user_service_pkg
./ucexec_pkg

For advanced diagnostics, include the user_service program logs when raising Unix Agent–related support cases.

Job Messenger and EVNT Handling

There are no functional changes in this area. Job Messenger behavior remains identical to previous versions and continues to be implemented as a native component written in C/C++.

UTF-8 Support and Case Handling in Agent Communication

Starting with version 24, Agents support UTF-8 encoding. UTF-8 behavior is controlled via the following INI parameter:

[VARIABLES]
; UTF-8 is the default for new agents
UC_HOST_CODE=<UTF-8>

When enabled, all data content—such as job reports, job data, and text-based Store object files—is written in UTF-8. Content encoding is prepared by the Automation Engine; the Agent is responsible only for writing the data as provided.

Internally, message elements have been migrated to string-based representations to enable automatic encoding conversion.

Unix Compatibility Settings

The Unix Agent also supports the legacy utf8=1 INI parameter. This setting exists solely for compatibility with older Unix Agents that do not natively support UTF-8. When utf8=1 is set, the default value of UC_HOST_CODE is interpreted as <UTF-8>.

Job- and Script-Level Encoding

UTF-8 encoding can additionally be enforced at the job or script level, independent of the global UC_HOST_CODE configuration.

Configuration and Behavioral Changes (V24.x)

This section provides a complete overview of configuration and behavioral changes introduced with the new Agent architecture, clearly distinguishing intentional design changes from behaviors that may indicate a defect.

The UC_HOST_CODE=<UTF-8> is only one intentional and incompatible change when installing the agent from scratch (new ini file).

Obsolete INI Parameters

Due to the redesigned Agent architecture—particularly in the areas of security, privilege separation, and internal message handling—the following INI parameters are now obsolete and have no functional impact, even if present in the configuration file:

readUserAlways =
vanishedRetry =
ft_Owner =
ServiceProgramStartCommand =
listenerUID =
listenerGID =
chiffre =
maxMsgSize =
maxRepCnt =
tcp_KeepAlive =
tcp_KeepAlive_Time =
FileBufferSize =
FileEndDelimiter =
fileRemoveCheck =
MsgToStdout =
processInfo =
start_Type =

File Transfer

The File Transfer object provides a File Attributes field. This field is primarily used to specify file attributes; however, for internal diagnostics, it can also be used to pass internal attributes and options that modify the behavior of a running file transfer. The options listed below are intended for testing and diagnostic purposes only and are not officially supported.

Internal File Transfer Attributes

Change the port number used to initiate the file transfer.

connect_port=<PORT-NR>

Change the IP address used to initiate the file transfer.

connect_ip=<IP-ADDR>

Specify the IP address used to bind the outgoing connection.

bind_addr=<IP-ADDR>

Force reverse connection for the file transfer (if Agent A cannot connect to Agent B, Agent B connects to Agent A).

reverse_connect=<Y/N>

Force renewal of the Agent TLS certificate.

simulate_ssl_connect_error=<Y/N>
simulate_ssl_cert_error=<Y/N>

Control whether destination disk space is checked before the transfer starts.

ft_check_free_disk_space=<Y/N>

Control whether disk space for the destination file is preallocated before transfer.

preallocate_file=<Y/N>

Control whether the file transfer report is sent to the Automation Engine.

ft_suppress_report=<Y/N>

Control whether a temporary file name is used on the destination before transfer.

ft_temp_file=<Y/N>

Set the socket buffer size for the sender session.

send_buffer_size=<size in bytes>

Set the socket buffer size for the receiver session.

recv_buffer_size=<size in bytes>

Connection timeout in milliseconds before the operation fails.

connect_timeout=<time in milliseconds>

Timeout in milliseconds for TLS connection response from the partner.

idle_timeout=<time in milliseconds>

Maximum time in milliseconds the transfer may wait without receiving data before failing.

ft_idle_timeout=<time in milliseconds>

Do not send file transfer start confirmation to the Automation Engine.

skipsendq=<Y/N>

Do not send file transfer start confirmation to the file transfer partner.

skiprecvq=<Y/N>

Equivalent to the HOST_CHAR_DEFAULT settings FT_ASYNC_QUIT_MAX, FT_ASYNC_QUIT_MIN, and FT_ASYNC_QUIT_NUM.

async_quit_values=<min/max/num>

Force the file transfer to fail after transferring a specified number of bytes.

ft_abort_on=<size in bytes>

Interval in seconds at which checksum generation triggers an internal report check for sending the FT report to the Automation Engine.

checksum_interval=<time in seconds>

Interval in milliseconds for internal report checks when sending the FT report to the Automation Engine.

report_interval=<time in milliseconds>

Interval in milliseconds at which internal file transfer status updates are sent to the Automation Engine.

status_interval=<time in milliseconds>

Control whether an MD5 checksum is generated (equivalent to FT_USE_MD5 in HOSTCHAR).

build_checksum=<Y/N>

Size of the internal buffer used to receive data from the file transfer partner.
Default: (FT_ASYNC_QUIT_MAX * 16000) / 2.

write_buffer_size=<size in bytes>

Hold the file transfer session for a specified time after transfer confirmation.

hold_session=<time in milliseconds>

Hold the file transfer session for a specified time after connection establishment.

hold_session_after_connect=<time in milliseconds>

Dump the complete message flow into the file transfer report if the session fails.

dump_session=<Y/N>

Enable detailed tracing in a temporary file, which is deleted on successful completion and retained only in case of error.

detailed_logging=<Y/N>

Performance Considerations of Java-Based Agents

Agent Runtime Performance

Agent runtime performance is comparable to prior (native) Agent versions and, depending on the workload and test scenario, may be equal or slightly improved. Performance characteristics remain workload-dependent, and no systemic performance regressions have been identified.

Agent Memory Consumption

Java-based Agents follow standard JVM memory management behavior. Without explicit configuration, the JVM may reserve significantly more memory than is required at runtime and may not release it back to the operating system. This behavior is reflected in the Agent log, for example:

U02000110 Maximum Heap Memory: '16384' MB

By default, the maximum JVM heap size may be set to 16 GB. While this is a virtual limit, the operating system may still reserve approximately 2 GB of memory (depending on the platform), which remains allocated even when actual memory usage is significantly lower. This can lead to resource bottlenecks, particularly on systems hosting multiple Agents.

Observed Memory Requirements

Based on internal testing, the Agent typically requires no more than approximately 256 MB of memory in total (around 200 MB JVM heap and 50 MB non-Java heap). Actual usage can be monitored through periodic memory reports written to the Agent log (every 10 minutes), for example:

U00045437 Memory usage: Heap '43' MB, Non-Heap '32' MB

These values can be used as input for environment-specific memory sizing.

Memory Configuration Recommendations

To control or restrict memory usage, JVM parameters can be passed via the Agent launcher. For example:

./ucxjlx6 -Xmx256m

This configuration limits the maximum JVM heap to 256 MB, resulting in an overall process memory footprint of approximately 300 MB at the operating system level (including JVM and non-JVM memory).

Platform-Specific Recommendation

On IBM systems, the use of the IBM Semeru JVM is recommended instead of HotSpot. IBM Semeru provides improved memory management characteristics on these platforms and is better suited for sustained Agent workloads.

Backward Compatibility

Job Definitions and Scripts

The primary design objective of the Java-based Agents is backward compatibility. No incompatible changes to job definitions, scripts, or execution semantics were intentionally introduced.
If a deviation is observed and it is not explicitly documented, it must be treated as a defect.

Logging, Monitoring, and Troubleshooting

General Troubleshooting

Most Agent startup failures are caused by an invalid runtime environment. Common issues include an unsupported Java version being resolved from PATH (for example, legacy Java 8). Ensure that a supported JVM version is installed and that all required system dependencies (such as libstdc++) are available.

Windows Agent

If the Windows Agent fails to start and no log file is generated, start the Agent with the --console parameter to display additional diagnostic output, including messages emitted directly by the JVM.

Unix Agent

On Unix systems, environment-related issues are typically visible through console output. A frequent source of errors is incorrect LIBPATH configuration. The JVM depends on libstdc++ libraries, and incorrect or inherited LIBPATH values (for example, from a service manager) may prevent the Agent from starting correctly.

Due to the additional architectural components involved in job execution (such as user_service), runtime issues may be difficult to diagnose using standard logs alone.

Enhanced Job-Level Diagnostics (JCL=9)

The JCL=9 trace flag is particularly useful for advanced diagnostics and has special significance:

• The generated job file is retained and not deleted

• The job is executed with tracing enabled, and the job report includes trace output

• The job execution is additionally traced using strace, providing low-level system call diagnostics
  (strace must be installed on the system)

JVM-Level Diagnostics

The Agent runs as a standard JVM application. In addition to Automation Engine logs and traces, standard Java diagnostic tools can be used. Commonly used tools include:

sudo jcmd <PID> VM.info

or jstack for thread analysis.

Network and TLS Debugging

Network Tracing

Application-level network diagnostics can be enabled by setting:

TCP/IP=5

This traces message content exchanged by the Agent.

TLS Debugging

TLS-related diagnostics can be enabled by starting the Agent with the following JVM option:

-Djavax.net.debug=<value>

Supported values include:

all turn on all debugging
ssl turn on ssl debugging

The following can be used with ssl:
  record       enable per-record tracing
  handshake    print each handshake message
  keygen       print key generation data
  session      print session activity
  defaultctx   print default SSL initialization
  sslctx       print SSLContext tracing
  sessioncache print session cache tracing
  keymanager   print key manager tracing
  trustmanager print trust manager tracing
  pluggability print pluggability tracing

handshake debugging can be widened with:
  data         hex dump of each handshake message
  verbose      verbose handshake message printing

record debugging can be widened with:
  plaintext    hex dump of record plaintext
  packet       print raw SSL/TLS packets

To list supported options for the active JVM:

java -Djavax.net.debug=help

 

AIX-Specific Troubleshooting

When running on AIX, verify the following:

• Sufficient free space is available in /tmp
  (The IBM JVM JIT writes temporary files to /tmp; insufficient space may cause a JIT abort and JVM dump.)

• IBM Semeru JVM is in use (also distributed via CAU packages)

• Required C++ runtime libraries are available:

  • libstdc++.a

  • libgcc_s.a
    In some cases, these must be linked in /lib or the Agent bin directory.

• LIBPATH is set correctly:

   

  export LIBPATH=/lib:/usr/lib

• IBM C++ Runtime 16.1.0.7 or later is installed (required by the JVM)

Additional Information

Refer to the Compatibility Matrix on the supported platforms/releases before installing the agent.