Installing agents from the command line#

Installing an agent from the command line involves running a batch file or shell script and specifying information about how the agent connects to the server or agent relay.

For production environments, create a user account that has the required privileges for the installation.

If the user account does not have the necessary privileges, the installation fails.

For AIX, HP, Solaris, Windows and Mac OS, the user account must have access to all working directories used in the process the agent runs.

For Linux and Unix OS, the user account must have root privileges in order to issue the su or sudo command when installing.
Make sure that your networks and firewalls allow communication on the required ports. See Firewall and communication configuration.
Ensure that each computer where you are installing an agent has a supported version of the Java™ Runtime Environment (JRE) or Java developer kit.
Set the JAVA_HOME system variable to the location of the JRE or JDK that you are using.
Ensure that there is no limit on the maximum memory size and virtual memory size. For example, on most Linux™ systems, you can run the ulimit -m and ulimit -v commands and ensure that both return the value unlimited. To find out how to remove the limit on the maximum memory size and virtual memory size, see the documentation for the operating system.

Agents can also be installed directly from the HCL™ Launch web application, see Installing agents remotely.

Agents can also be installed directly from the HCL Launch web application, see Installing agents remotely.

For simple evaluations, the administrative user can run the agent on the computer where the server is located. Because agent workloads can be resource-intensive, for production environments, do not install agents on the computer where the HCL Launch server is located. If you plan to run deployments on several target servers, install a separate agent on each one. If, for example, your testing environment consists of three servers, install an agent on each one. Follow the same procedure for each environment the application uses.

Each agent requires the appropriate rights to communicate with the HCL Launch server.

At a minimum, each agent must have these permissions:

Open a TCP connection. A Web agent uses one for its WebSocket connection.
Open a HTTP(S) connection. The agent must be able to connect to the HCL Launch user interface to download artifacts from the CodeStation repository.
Access the file system. Many agents need read/write permissions to items on the file system.

If the agent communicates with HCL Launch by using an agent relay, you can install the agent from the command line.

To install an agent from the command line:
Download and extract the agent installer using any one of the following ways:
- To download the installer, log in to the server and click the Help icon at the upper right of any page on the server, and click Tools. Then, click HCL Launch Agent, and download and extract the file.
- To find the installer on the server with the command line, go to the following location, and copy the file to the target computer: installation_folder/opt/tomcat/webapps/ROOT/tools/ucd-agent.zip
- After you download and expand the installation package, open the installer directory.
From this directory, run the install-agent.bat command (Windows™) or install-agent.sh (UNIX™, Linux, Mac OS, or IBM z/OS®).

Note: If you install the agent as a Windows service, the user account must have the following privileges:
- SE_INCREASE_QUOTA_NAME "Adjust memory quotas for a process"
- SE_ASSIGNPRIMARYTOKEN_NAME "Replace a process level token"
- SE_INTERACTIVE_LOGON_NAME "Logon locally" The HCL Launch agent installer is displayed and prompts you to provide the following information. You can accept the default values (displayed in brackets) by pressing Enter. If two options are given, such as Y/n, the uppercase option is the default value. Depending on the options that you select, different prompts display.
- For all agents, provide values for the following prompts:
  - *Enter the directory where agent should be installed.*
    
    For example, enter C:\Program Files\agentDir (Windows™) or /opt/IBM/ucd/agent (UNIX™). If the directory does not exist, enter Y to instruct the Installer to create it for you. If you enter an existing directory, the program gives you the option to upgrade the agent. For information about upgrading, see Upgrading agents.
    
    Note: Do not use any shell expansions or abbreviations, such as the tilde character (~).
  - *Please enter the home directory of the JRE/JDK used to run this agent.*
    
    If Java™ is already installed, HCL™ Launch suggests the Java™ location as the default value. To accept the default value, press Enter. Otherwise, override the default value, and enter the correct path.
  - *Will the agent connect to an agent relay instead of directly to the server?*
    
    The default value is N. To configure a connection to an agent relay instead of a connection to the server, specify Y. If you connect directly to a server, complete step 3.b. If you connect to an agent relay, complete step 3.c.
- If the agent connects directly to the server, provide values for the following prompts:
  - Enter the full URI for the server this agent will connect to.****
    
    Specify the secure WebSocket connection URI. The format is wss://hostname:port. The default value is wss://localhost:7919.
  - *Enter the hostname or address of the server the agent will connect to.*
    
    If you are connecting the agent to a high-availability cluster of servers, specify one server in the cluster here and add the other servers as failover connections. Do not specify the host name of the load balancer. The default value is localhost.
    - *Enter the hostname or address of the server the agent will connect to.*
      
      The default value is localhost.
    - *Enter the agent communication port for the server.*
    - *Do you want to configure another failover server connection?*
      
      The default value is N. To specify another failover server, press Y.
- If the agent connects to an agent relay, provide values for the following prompts:
  - *Enter the hostname or address of the agent relay the agent will connect to.*
    
    Enter the host name or IP address of the agent relay. Specify the value that you used when you installed the agent relay.
    - *Enter the hostname or address of the agent relay the agent will connect to.*
      
      You must provide the hostname or address of the agent relay.
    - *Enter the agent communication port for the agent relay.*
    - *Do you want to configure another failover agent relay connection?*
      
      The default value is N. To specify another failover server, press Y.
  - *Enter the hostname or address of the HTTP proxy server for the agent relay.*
    
    The default value is the hostname or address of the agent relay that you provided.
  - *Enter the HTTP proxy port for the agent relay.*
    
    Enter the port that the agent uses for HTTP communications with the agent relay. The default value is 20080.
  - *Do you want to disable HTTP Failover Handling?*
    
    The default value is N. You must disable HTTP failover handling if the relay is behind a firewall and accessed through a load balancer. To disable HTTP failover handling, press Y.
- For Web agents, provide values for the following prompts:
  - *Enter the name for this agent.*
    
    Enter a unique name. The server uses this name to identify this agent. Names are limited to 256 characters and cannot be changed.
  - *Enter teams (and types) to add this agent to, separated by commas.*
    
    The default value is None.
    
    Agents can be added to teams the first time they connect to the server. The agent is assigned to the specific teams the first time that it connects to the server. Separate multiple teams by commas. Trailing spaces are ignored. Team names that do not exist are also ignored. To specify the agent's security type for a team, provide the team and security type in the following format: team:type.
  - *Do you want to install the Agent as Windows service?*
    
    This parameter applies only to Windows™. The default value is N. When installed as a service, HCL™ Launch captures the PATH variable values. Any changes to the values after the service is installed will be used by the agent process when it starts up. For recent versions of Windows™, you must run the command as Administrator.

Upgraded or installed agents are migrated to compact mode. Note that agents are updated to compact only if the agent is installed/upgraded on a platform that supports compact agents.

Parent topic: Installing agents

Related information

Impersonation on Linux and UNIX systems