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 system where the agent is installed.
Ensure that each computer where you are
installing an agent has Java™ Runtime
Environment (JRE) or Java Development
Kit (JDK) version 7 or later.
If
the target computer has an IBM® JRE
or JDK, update the JRE or JDK to version 7.0.0 SR4 with the specified
service refresh (SR) level or a later service refresh level:
About this task
Agents that run on UNIX systems
can 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 system where the server is located.
But if you plan to run deployments on several systems, install a separate
agent on each system. If, for example, your testing environment consists
of three systems, install an agent on each one. Follow the same procedure
for each environment the application uses.
Each agent needs
the appropriate rights to communicate with the IBM UrbanCode Deploy server
(if the agent communicates with IBM UrbanCode Deploy via
an agent relay, see Installing agents remotely).
At a minimum, each agent must have permission
to:
- Create a cache. By default, the cache is in the home directory
of the user that runs the agent. The cache can be moved or disabled.
- 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
- Download and extract the agent installer to the computer
on which you want to install the agent:
- To download the installer from the server, click the Help
button at the
top right of the page and then 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 system: installation_folder/opt/tomcat/webapps/ROOT/tools/ibm-ucd-agent.zip
Note: If
you are installing the agent on z/OS®,
the character encoding for several text-type files in the installation
package must be converted to IBM-1047 encoding before they can be
used. Extract the installation files and convert the following files
to IBM-1047 encoding:
- install-agent.sh
- install.with.groovy.xml
- opt/apache-ant-1.8.4/bin/ant
- opt/apache-ant-1.8.4/bin/antRun
- opt/groovy-1.8.8/bin/groovy
- opt/groovy-1.8.8/bin/startGroovy
- install/AgentInstaller.groovy
To convert the files, issue commands similar to the following
text at a command prompt:
iconv -f UTF-8 -t IBM-1047 filename >filename.bac
mv filename.bac filename
After
converting the files, move the installation files to z/OS and continue with installation.
- After you download and expand the installation package,
open the installer directory.
- From this directory, run install-agent.bat (Windows) or install-agent.sh (UNIX or Linux).
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 within brackets) by pressing
Enter. If two options are given, such as Y/n, the
capitalized option is the default value.- Enter the directory where agent should be installed.
- For example: 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 IBM UrbanCode Deploy.
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 the following parameters:
- hostname or address of the agent relay the agent will
connect to
- Enter the host name or IP address of the agent relay. Supply 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 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.
Note: You can specify another relay to use in the case
the first one fails. Configure fail-over relays by appending additional
relays to the locked/agent.brokerUrl=failover\: parameter
in the /agent-install/conf/agent/installed.properties file.
Relay configuration syntax is agent_IP_or_hostname\:JMS_port.
Separate relays by commas. The following example shows the parameter
configured for two relays: locked/agent.brokerUrl=failover\:(ah3\://relay1\:7916,ah3\://relay2\:7916).
It is assumed that all relays use the same HTTP proxy port. Initially,
the parameter contains the location of the relay configured during
agent installation.
- Enter the host name or address of the server the agent
will connect to.
- The default value is localhost. If the agent
is connecting to clustered servers, specify the host name of the load
balancer.
- Enter the agent communication port for the server
- The default value is 7918.
- Does the server agent communication use mutual authentication
with SSL?
- The default value is N.
If you use SSL, turn
it on for server too or the agent will not be able to connect to the
server. This also applies if you are using mutual authentication.
If you change the port numbers for agent communication, you must provide
them while you install the agents.
- 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 first time
the agent connects to the server it will be assigned to the specified
teams. 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?
- (Windows only). 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 Windows versions, you must run
the command as Administrator.
What to do next
Start the agent as described in
Starting agents.
If the agent is configured properly,
IBM UrbanCode Deploy recognizes
it automatically; you do not need to perform further actions to start
using it.