Installing the Agent for Windows (Java)

Important! These installation instructions apply only to the installation of Java-based x64 Windows agents.

The Java Agents require a JRE (version 11 or higher) and the latest version of the Microsoft Visual C++ Redistributable Package.

This page guides you through the installation of a Java based x64 Windows Agent in an AE system without using authentication. If you want to use one of the authentications methods available, you need to follow additional installation steps. For more information, see Agent Authentication.

Check the compatibility matrix to see which version is compatible with your system. For more information, see Compatibility Information.

This Agent supports sending emails using SMTP and SMTPS. For more information, see Setting Up Email Connections.

Recommendation: Install the Agent in a separate directory (such as C:\AUTOMIC\AGENT\WINDOWS). Make sure that you do not use either camel case in the host name nor leading zeros in the IP address.

Tip! This page refers only to the manual installation process. If you want instructions on how to install a containerized Windows agent, see Installing Containerized Windows Agents.

Watch the Video: Installing Windows Agents

This page includes the following:

Overview

The Agent consists of two components:

  • A launcher application called ucxjwx6.exe

  • A Java archive (the JAR file called ucxjoss.jar)

Both are located in the Agent's bin directory. The launcher detects and starts an available Java Runtime Environment (JRE) and then loads the application provided in the JAR file.

Important! Use only the launcher to start the Agent, DO NOT try to load the JAR file manually in a JRE, as the launcher performs important preparations for the Agent to function correctly.

Java Runtime Environment (JRE)

The Agent requires a JRE (version 11 or higher). You can make it available either through a system-wide Java installation of through a minimal JRE version.

When started, the Agent's launcher application looks for the JRE using on of the following methods:

  1. Finding and starting the JRE from the jre subdirectory in the Agent's bin directory. The jre directory is either supplied by the CAU or it can be installed manually.

  2. Using the JAVA_HOME environment variable.

  3. Executing the java -XshowSettings:properties command to find a working Java installation. The launcher uses the PATH environment variable to locate the executable. If the this command succeeds (which means that the JVM starts), the path of the running JVM is retrieved from the command's output.

The launcher then starts the JRE and loads the Agent's jar file.

Additional Rights Required

The Windows Agent requires certain additional rights under Windows in order to be able to use the Windows APIs that are listed below.

The Agent requires these rights in order to process file transfers and start jobs in different user contexts. Although users are defined in the Automation Engine jobs, the Agent must still be able to log on with the privileges of the particular user, read user profiles and start Jobs, for example. Therefore, start the Agent via the Service Manager as a SYSTEM user.

When you start the Agent as a regular user, however, you should install it with the recommended additional authorizations in order to make sure that it can process the above tasks:

  • Act as part of the operating system
  • Adjust memory quotas for a process
  • Back up files and directories
  • Log on as a service
  • Replace a process level token
  • Restore files and directories

The right 'log on as a batch job' is required when the option "log on as a batch user" has been activated in the Windows Jobs of the AE system's Job objects.

Powershell Configuration - File Backup or Rollback

The Agent must be configured to be able to execute Powershell commands for file backup or rollback. To do so, add the following key-value pairs in the [GLOBAL] section of the INI file of the Windows Agent:

ECPEXE=powershell.exe -NonInteractive -ExecutionPolicy bypass -NoLogo -file

Note: To run powershell scripts, the line below must be uncommented in the HEADER.WINDOWS object in Client 0:

:INC HEADER.WINDOWS.PWSH.HEAD ,nofound=ignore

Connecting to the Automation Engine

The Automation Engine and the Windows, UNIX, and Java Agents communicate using TLS/SSL. These agents establish a connection with the Java communication process (JCP), which uses trusted certificates to prove their identity to other communication partners.

Important! Make sure you are familiar with the TLS/SSL and certificate implementation before installing and/or upgrading the respective component. For more information, see:

When you used certificates signed by a CA, the certificates are stored in the respective Java or OS store by default; that is the Java trust store for Java components and Java Agents, the Windows OS store for Windows Agents, or the TLS/SSL store for UNIX Agents. In this case, you only have to check that the root certificates already are in the respective store.

If the relevant certificates are not there and you want to import them, you can use OS or Java specific tools for that purpose, such as Keytool, cert-manager, OpenSSL and such. For more information on how to use those tools, please refer to the respective product documentation.

If you do not want to use the default locations for the components and Agents listed above, make sure you use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters (if applicable) in the respective configuration (INI) file to define the path to the folder where the trusted certificates are stored.

Important! TLS/SSL Agents (in containers and on-premises) as well as the TLS Gateway, when used for the Automic Automation Kubernetes Edition, establish a connection to an ingress / HTTPS load balancer, which requires a certificate for authentication.

Make sure that address of the load balancer is defined on both sides: the Automation Engine and the Agent / TLS Gateway and that your HTTPS load balancer has the required certificates in place. For more information, see Connecting to AWI, the JCP and REST Processes Using an Ingress.

Installing the Agent

Follow the steps below to install the Agent.

  1. Install the Microsoft Visual C++ Redistributable Package.

    This installation step can be ignored if the package is already available in the required version. Go to Control Panel > Add or Remove Programs to see if the package is installed, and if so, which version.

    If it is not, install the package from the IMAGE:EXTERNAL.RESOURCES\CRTS2017\X64 directory.

  2. Install the Agent.

    1. Start the program SETUP.EXE in the IMAGE:AUTOMATION.PLATFORM\AGENTS\WINDOWS\java directory.

    2. Select a separate directory for the Agent, for example, C:\AUTOMIC\AGENT\WINDOWS. Click the large button (computer, packing and disc) to start the installation.

      The Automic program group is automatically created and the Agent specified.

  3. Set up the system environment.

    • On the host, adjust the INI file of the Windows Agent (64-bit) to your system environment. For more information, see Agent Windows 64-bit.

      When you used certificates signed by a CA, the certificates are stored in the respective Java or OS store by default. In this case, you only have to check that the root certificates already are in the respective store.

      If you do not want to use the default location for this component, make sure you use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters (if applicable) in the respective configuration (INI) file to define the path to the folder where the trusted certificates are stored.

      For more information, see Securing Connections to the AE (TLS/SSL).

      The user who starts the agent must have the following rights if the logon= parameter in the INI file of the agent is set to 1 (default):

      • Act as part of the operating system
      • Adjust memory quotas for a process
      • Allow log on locally
      • Back up files and directories **)
      • Logon as batch job *)
      • Logon as service
      • Replace a process level token
      • Restore files and directories

      *) This right is only required if you start jobs by using the start option Logon as batch user.

      For more information, see Windows Jobs.

      **) This right is necessary for the execution of job objects.

      For the extended File Transfer object (as of v9) this right is usually optional. It is necessary, however, when the agent transfers encrypted files with a file transfer because the agent uses the WinAPI LoadUserProfile.

      On Windows, the Local Security Policy can be called via the Control Panel > Administrative Tools. Rights are defined in User Rights Assignment in the Local Security settings.

      All Windows users that should execute BATCH-type jobs required the right Read & Execute for the agent's bin and temp directories. Otherwise, an error message occurs when the job starts (Access denied). This is necessary when the logon= parameter in the INI file of the agent is set to 1 (default) or the UC_HOSTCHAR_*'s setting ANONYMOUS_JOB is set to "N".

    • On the Admin or server computer, adjust HEADER.WINDOWS, TRAILER.WINDOWS and RESTART.WINDOWS if necessary. For more information, see Include (JOBI) Objects in Headers and Trailers.

  4. Start the Agent. Make sure that the AE is running, see Multi-Server Operations.

    You have the following options:

    • Using the command line to call the Agent's launcher (.\ucxjwx6.exe).

    • From the Windows Start menu. To do so, open the Start menu, navigate to the Automic folder and click the Windows Agent.

    • Using the ServiceManager.

    From the command line or when using the ServiceManager, you can pass the following parameters:

    • -svc%port%: When specified, the ServiceManager displays the connection status along with the Agent name.

    • -i<ini-file>: starts the Agent with a specific INI file

      Example Service Manager

      ucxjwx6.exe -svc%port% -Ic:\Agent\Agent-Windows.ini

      Note: The -svc parameter should be omitted when starting directly via the command line.

    • --console: Allows you to detect problems in the Agent startup phase. The output is displayed in the Windows CLI Window.

      Example CLI

      ucxjwx6.exe --console

Regardless of the option you use to start the Agent, an Agent object is automatically created in Client 0 and stored in the folder HOST. You can configure access permissions to those folders, see Folders (FOLD).

In AWI, client 0, verify that the Agent is logged on to the Automation Engine.

Newly logged on Agents are not assigned to a client automatically and can only be viewed in Client 0. Once you have logged in to Client 0, access the Administration perspective and select Agents & Groups.

Assign the new Agent to clients with the required rights using the Agent object definition. For more information, see Authorizations Page.

Shutting Down the Agent

You can use the ServiceManager not only to start but also to end the Agent as a service, see ServiceManager.

Alternatively, you can shut down the Agent using one of the following options:

  • On the host, right-click the Agent in the task bar and selecting Exit.

  • In AWI: In the Agents section of the Administration perspective, right-click the relevant and select Stop.

See also: