Installing HCL UnO agent

HCL UnO agent is a versatile on premises agent that can run all types of tasks with efficiency and reliability. You can configure the properties of the agent to connect it to the agent manager of HCL Universal Orchestrator.

Before you begin

Before installing the agent, perform the following steps:

Download the HCL UnO agent package from the Download Center of the UI, or you by opening the following URL and selecting a package from the available extensions:
```
https://hostname:port_number/twsd/api/v2/executable
```
Where:

hostname

The hostname of the gateway microservice.

port_number

The valid port exposed for API gateway. The default port is 443.

If you are using the UI, click the user icon, and then select the Download Center option from the drop down list to download the files for HCL UnO agent. The file for the agent contains the following folders:
- iso-swid
  
  The folder contains hcltechsw.com_HCL_agent.swidtag file, an XML file for inventory tracking.
- bin
  The folder contains the following files:
  - configure.sh: The script to install the agent in Unix operating system.
  - configure.ps1: The script to install the agent in Windows operating system.
  - hcl-uno-agent-VERSION.jar: The agent jar file.
- licenses
  
  The folder contains notices and license agreements associated with the agent.
Download and install javaJDK version 21 or above.
Ensure free space of minimum 800 MB (500 MB for temp directory and 300 MB for installation) and 1 GB RAM in computer.
Create a valid API Key for initial authentication. The API Key must have the following security roles permissions:
- REGISTERAGENT.
- ADD for the workstation item in the folder where you will install the agent.
You can manage security roles from the Orchestration CLI. For more information, see: Managing security roles from the Orchestration CLI.
You can find more information about API Keys in Managing authentication using API Keys.

About this task

The configuration step connects the agent to the agent manager, test the connection, download the certificates and complete all the set-ups needed for the agent to run successfully. On successfully configuring the agent, a directory named .uno-agent is created by default, if you do not specify any value for the optional parameter dataDir. The mandatory and optional parameters that you can set to configure the agent is described in the following procedure. All the parameters to set up the agent is saved into one single file called agent.properties and is stored under the directory.

Procedure

Extract the contents from the downloaded HCL UnO agent package.

Note: If required, you can override the JAVA_HOME environment variable to change the java version for the current user session. To modify the environment variable, use the specific commands according to the operating system you are using.

Open the command line and run the command as follows:

configure.ps1 [Mandatory parameters=value] [Optional parameters=value]

./configure.sh [Mandatory parameters=value] [Optional parameters=value]

Enter valid details for the mandatory parameters. If required, you can add the optional parameters also.

Table 1. Mandatory parameters
Option	Action
--agentName or -n	Enter the agent name with the folder path where you want to install the agent.
--agentManagerUrl or -u	Enter the URL to connect to the agent manager of HCL Universal Orchestrator.
--apiKey or -k	Enter the API key.
--licenseAccepted	Add the option to accept the license. If accepted, when the configuration is completed the license is copied to the directory.

Note: If you do not add any one of these parameters, an informational message is displayed to add the value for the missing parameter.

The optional parameters that you can add are as follows:

Table 2. Optional parameters
Option	Action
--certificateAccepted	If you do not have valid certificates, add this option. It gets certificates from the agent manager and stores them in the following paths: c:\Users\`user_name`\.uno-agent\security\certs home/`user_name`/.uno-agent/security/certs
--commonTempPath property or -ctp	You can specify the file path for the jobprop.exe file. For more information, see Defining variables with the jobprop utility.
--completedTaskMaxAge-- or -ma-	You can set a limit in days for deleting all files, logs, and other resources associated with the agent workflow. The value must be higher than 7 days or else it is set to the default value, which is 30 days.
--dataDir or -d	You can specify the path to the folder to create the directory. If no path is given, a directory with files and folders is created as follows: home/`user_name`/.uno-agent c:\Users\`user_name`\.uno-agent Note: If you configure the agent using Powershell and the file path contains spaces, ensure that the file path is enclosed within single or double quotes, or an error occurs.
--logLevel or -l	You can use this option to filter the log messages that are retrieved in the cli.log file. The file is created under the .uno-agent folder. When you set a value, all the messages equal to that severity and above are sorted. The default value is `INFO`. You can enter any one of the following message types. The message types are listed from lower to higher severity. `FINEST`: Messages that indicates a highly detailed application flow. `FINER`: Messages that indicates a fairly detailed application flow. `FINE`: Messages that indicates the application flow. `CONFIG`: Static configuration messages are filtered. `INFO`:Any additional information which are not tied to the current task or action. `WARNING`:Messages that indicates a potential problem. `SEVERE`: Messages that indicates a serious failure. In addition, you can use `OFF` to turn off and `ALL` to record all types of messages. Note: The logs are displayed in English only, if you select the log level `CONFIG` or below. The logs are placed in the following paths: c:\Users\`user_name`\.uno-agent\stdlist\cli.logs home/`user_name`/.uno-agent/stdlist/cli.logs
--messageLogLevel or -ml	You can use this option to filter the messages that are retrieved in the messages.log file. The file is created under the .uno-agent folder. When you set a value, all the messages equal to that severity and above are sorted. The default value is `INFO`. You can enter any one of the following message types. The message types are listed from lower to higher severity. `FINEST`: Messages that indicates a highly detailed application flow. `FINER`: Messages that indicates a fairly detailed application flow. `FINE`: Messages that indicates the application flow. `CONFIG`: Static configuration messages are filtered. `INFO`:Any additional information which are not tied to the current task or action. `WARNING`:Messages that indicates a potential problem. `SEVERE`: Messages that indicates a serious failure. In addition, you can use `OFF` to turn off and `ALL` to record all types of messages. Note: The logs are displayed in English only, if you select the message log level `CONFIG` or below.
--messageLogRotation or -mr	You can set a value for maximum number of message files and after the specified value is reached, all the message files are deleted. The default value is 10.
--messageLogSize or -ms	You can define the maximum size of a single message file. The default value is 10 M. You can specify any value ranging from bytes (B) to Gigabytes (G), depending on your environment.
--proxyUrl or -pu	You can specify a valid URL to enable the use of a proxy. Use a URL with HTTP or HTTPS as protocol.
--proxyUsername or -pn	You can specify a valid user name, if you have added the proxyUrl. This ensures an authenticated connection with the engine.
--proxyPassword or -pp	You can specify a valid password, if you have added proxyUrl and proxyPassword for an authenticated connection. If no values are given, then `admin` is added by default.
--traceLogLevel or -tl	You can use this option to filter the trace files that are retrieved in the trace.log file. The file is created under the .uno-agent folder. When you set a value, all the traces equal to that severity and above are sorted. The default value is `INFO`. You can enter any one of the following types. The types are listed from lower to higher severity. `FINEST`: Traces that indicates a highly detailed application flow. `FINER`: Traces that indicates a fairly detailed application flow. `FINE`: Traces that indicates the application flow. `CONFIG`: Static configuration messages are filtered. `INFO`:Any additional information which are not tied to the current task or action. `WARNING`:Traces that indicates a potential problem. `SEVERE`: Traces that indicates a serious failure. In addition, you can use `OFF` to turn off and `ALL` to record all types of trace messages. Note: The logs are displayed in English only, if you select the trace level `CONFIG` or below.
--traceLogRotation or -tr	You can set a value for maximum number of trace files and after the specified value is reached, all the trace files are deleted. The default value is 10.
--traceLogSize or -ts	You can define the maximum size of a single trace file. The default value is 10 M. You can specify any value ranging from bytes (B) to Gigabytes (G), depending on your environment.
--fileMonitorTimeout or -fmt	You can modify the default value for timeout attribute. For more information, seeFile monitor tasks.
--fileMonitorPolling or -fmp	You can modify the default value for polling attribute. For more information, seeFile monitor tasks.
--fileMonitor or --fmr	For more information, seeFile monitor tasks.
--blacklistedDir or -bld	You can restrict any specific file paths when you run a file monitor task. For more information, see File monitor tasks.

Note: You can run the --help or -h option to view the list and abbreviation of each option. You can also run the --version or v option to get the details of the installed version.

Press Enter.

Note: After you configure the agent, the workstation is created with LINKED status. You must run the agent within few minutes or else it shifts to UNLINKED status. If any tasks are submitted during this time frame, they become stuck at INTRO status initially and later reverted to READY status when the agent shifts to UNLINK status.

Results

You have successfully installed the agent and related files and folders are created under the directory. For more information, see Folder structure and file management for HCL UnO agent in Windows operating systems or Folder structure and file management for HCL UnO agent in Unix operating systems.

Note: For operating systems that support POSIX, the permissions granted for all types of files by default are as follows:


Type	Permissions
Files	rw-r-----
Directories	rwxr-x---
Executables	rwxr-x---

To update any values in the agent.properties file, you can reconfigure the agent using the configure command. For more information, see Reconfiguring HCL UnO agent.

Example

In the following example, you can find a command to configure HCL UnO agent:

./configure.sh --agentManagerUrl https://agentmanager.uno.nip.io -d /UnO_Agent --agentName /AGENT1 --apiKey valid_apiKey  --licenseAccepted --certificateAccepted

In the following example, you can find a command to configure HCL UnO agent on the HCL Universal Orchestrator folder named HCL_AGENT.

./configure.sh --agentManagerUrl https://agentmanager.uno.nip.io -d /UnO_Agent --agentName /HCL_AGENT/AGENT1 --apiKey valid_apiKey  --licenseAccepted --certificateAccepted

What to do next

You can now use the agent configuration to manage the HCL UnO agent. For more information, see Managing HCL UnO agent in Windows operating systems or Managing HCL UnO agent in Unix operating systems.