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.

Before you begin

For production environments, create a user account that is dedicated to running the agent on the server where the agent is installed.
Note: This user must have access to all working directories that are used in the processes that this agent runs. If this user does not have access to the working directory specified in a process step, that step fails.
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 Development Kit (JDK). For more information, see System requirements.
If the target computer has an IBM® JRE or JDK, update to a supported version of the IBM JRE or JDK.
Set the JAVA_HOME system variable to the location of the JRE or JDK that you are using.

About this task

Agents can also be installed directly from the IBM UrbanCode™ Deploy 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 IBM UrbanCode Deploy 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 IBM UrbanCode Deploy server (if the agent communicates with IBM UrbanCode Deploy by using an agent relay, see Installing agents remotely).

At a minimum, each agent must have these permissions:

Open a TCP connection. The agent uses a TCP connection to communicate with the server's JMS port.
Open a HTTP(S) connection. The agent must be able to connect to the IBM UrbanCode Deploy 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.

Procedure

To install an agent from the command line:

Download and extract the agent installer to the computer to install the agent on. Complete one of these steps:
- 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 IBM UrbanCode Deploy 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/ibm-ucd-agent.zip
  Note: If you are installing the agent on IBM z/OS® by extracting files to the UNIX file system, you must convert the character encoding for several text-type files in the installation package to IBM-1047 encoding. If you are installing the agent by using SMP/E, you do not have to convert the character encoding. Move the installation files to the z/OS computer, and then extract the files. If the z/OS computer does not have the unzip program installed, use the jar command to extract the files. For instance, type the following text at a command prompt:
```
JAVA_HOME/bin/jar xvf ibm-ucd-agent.zip
```
  Run the convertFilesForZos.sh script to convert the character encoding of the relevant files to IBM-1047 encoding. After you convert the files, continue with installation.
  Note: If you are installing the agent on IBM i, you must run the commands through the IBM Portable Application Solutions Environment for i (PASE for i) shell. Move the installation files to the i system, and then extract the files. Run the ibmi-compatability-fix.sh script to update the installer to use the PASE for i shell. After you run the script, continue with installation.
After you download and expand the installation package, open the installer directory.
From this directory, run install-agent.bat command (Windows) or install-agent.sh (UNIX, Linux, Mac OS, or IBM i).
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 IBM UrbanCode Deploy 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.
Enter the directory where agent should be installed.

For example, enter C:\Program Files\IBM\UCDeploy-agent (Windows) or /opt/IBM/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 the server.
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 the agent.

If Java™ is already installed, IBM UrbanCode Deploy 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 a agent relay instead of directly to the server?

The default value is N. If you specify Y, you are prompted to configure these parameters:
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.

agent communication port for the agent relay

Enter the port that the agent uses for JMS-based communications with the agent relay. The default value is 7916.

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.

Enter the host name or address of the server the agent will connect to.

The default value is localhost.

Enter the agent communication port for the server

The default value is 7918.

Do you want to configure another failover server connection?

The default value is N. If you specify a failover server, the agent connects to that failover server if the main server fails.
To configure a failover server, type y and then press Enter.

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.

The default value is 7918.

Do you want to configure another failover server connection?

The default value is N. To specify another failover server, press Y.

Does the server agent communication use mutual authentication with SSL?

The default value is N.
If you use mutual authentication, you must manually exchange a key between the server and each agent or agent relay. For more information about this option, see Configuring mutual authentication.

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 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.

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, IBM UrbanCode Deploy captures only the value for the PATH variable. Values that are captured during installation are always used, even if you change them later. For recent versions of Windows, you must run the command as Administrator.

What to do next

Start the agent as described in Starting agents. If you correctly configured the agent, IBM UrbanCode Deploy recognizes it automatically. You do not have to take further actions before you use it.

Feedback