An agent relay is a communication proxy for agents that
are located behind a firewall or in another network location.
About this task
While there is at least a low-bandwidth WAN connection
between the server and remote agents, the IBM UrbanCode Deploy server
can send work to agents in other geographic locations through the
relay. An agent relay requires that only a single server in the remote
network contact the server. Other remote agents communicate with the
server by using the agent relay. All agent-server communication from
the remote network goes through the relay.
Procedure
- Download and extract the agent relay installer to the computer
on which you want to install the agent relay:
- To download the installer from the server, click Help at
the upper right of the page and then click Tools.
Then, click IBM UrbanCode Deploy Agent
Relay 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/agent-relay.zip
- Expand the compressed installation file.
- From within the expanded agent-relay-install directory,
run the install.cmd script (Windows) or the install.sh file
(Linux or UNIX).
- The installation program prompts you for 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 to install the agent relay into.
- Enter the directory for the relay. If you enter an existing directory,
the program prompts you to upgrade the relay. For information about
upgrading, see Upgrading the server. The default
value is /opt/ibm/agentrelay.
- The specified directory does not exist. Do you want to create
it?
- Press Y to create the installation directory.
- Enter the home directory of the JRE/JDK used to run
the Agent Relay.
- Specify the directory in which Java is
installed. Ensure that the JAVA_HOME environment
variable points to this directory.
- Enter a unique name for this relay.
- Enter the name of the agent relay. Each relay must have a unique
name. The default name is agent-relay.
- Enter the IP address or host name that this Agent Relay
listens for requests on.
- Enter the IP address or host name on which the relay listens.
In most cases, agent listens on all IP addresses that are available
to the computer; in this case, specify 0.0.0.0.
- Enter the port number that this Agent Relay listens
for proxy HTTP requests on.
- Enter the port on which the agent relay listens for HTTP requests
coming from agents. The default value is 20080.
Note: In addition,
the relay automatically listens for CodeStation requests on port HTTP_proxy
+ 1 on the system where the agent relay is located. If you
use the default port for HTTP requests, the relay uses 20081 for CodeStation
requests and artifact transfers. If the CodeStation request port is
blocked, agents cannot download artifacts.
- Enter the port number that this Agent Relay uses for
JMS communication.
- Enter the port that the agent relay uses for JMS-based communications
with remote agents. The default value is 7916.
- Do you want to connect the agent relay to one or more
central servers?
- Specify whether you want the relay to connect to the IBM UrbanCode Deploy server.
Note: If
you do not connect to the server now, you must configure a network
relay so that the server can initiate communication with this agent
relay. See
Creating network relays.
- Enter the hostname or address of the server that this
relay will connect to.
- If you indicated that you want to connect the relay to a server, specify the IP or host name
where the relay can contact the server. If you specify a host name, make sure that
the relay computer can resolve the host name to an IP address via DNS.
- Enter the agent JMS communication port number for the
server.
- If you indicated that you want to connect the relay to a server,
enter the port that the server uses to communicate with agents. The
default value is 7918.
- Do you want to configure an additional connection for failover
scenarios?
- If you specify a failover connection, when the primary sever is not available, the agent relay
connects to a failover server.
- Enter the hostname or address of the server that this relay will
connect to.
- Specify the IP or host name of the failover server.
- Enter the agent JMS communication port number for the server.
- Enter the port that the server uses to communicate with agents.
The default value is 7918.
- Do you want to use mutual authentication between the
agent, relay and server?
- If mutual authentication is necessary, enter Y.
See Configuring mutual authentication for information
about activating mutual authentication.
- Do you want to cache files on the relay that are downloaded
by connected agents?
- If you want to cache files on the agent relay, enter Y.
- What is the storage limit for cached artifact storage?
- If you are caching files on this relay, you can specify a storage
limit for those files. You can specify a number of bytes, or use the
extensions "K," "M," "G,"
or "T" to indicate kilobytes, megabytes, gigabytes,
and terabytes. For example, to specify 5 gigabytes, type 5G.
When the storage limit is exceeded, the agent relay removes files
based on which files have not been used in the longest time.
- Enter each status for which you want to cache components,
one status per line, with an empty line to end the list.
- If you choose to cache files on the relay, this option is available.
The relay can cache components based on component version status.
Enter component statuses, one status per line. A status can contain
a space except in the first or last position. A status can contain
commas. The special * status replicates all artifacts.
To end the list, press Enter on an empty line. If no value is specified,
no component versions are replicated.
Note: Statuses are stored in
the agentrelay.codestation.geotags property in the relay_install/conf/agentrelay.properties file.
In the file, statuses are separated by commas. If you edit a status
that contains a comma, the comma must be escaped. For example, a status
that is named Hello, world is represented this
way: agentrelay.codestation.geotags=Hello%2c World.
- Enter the full web URL for the central server.
- Enter the complete URL, that uses the following syntax: scheme://domain:port. For
example: https://myServer.com:8080.
- Provide an authentication token for the associated user account
on the central server.
- Type or paste the token that is created for the relay. If you
chose the component replication option, the user that is associated
with the token must have the Read Artifact Set List permission.
For information about tokens, see Setting server configuration security.
Note: If you did not create a token previously,
you can create one now and then continue installation.
- Which user do you want to run the agent relay?
- The default value is agentrelay.
- Which group do you want to run the agent relay?
- The default value is agentrelay.
- Do you want to install the Agent Relay as Windows service?
- If you are installing the relay on Windows, you can install it as a Windows service. The default value is N.
- If the relay is on Linux or UNIX and will connect to 400 or more agents, increase the
process and file limit for the server:
- Add the following lines to the file that sets process and file limits. For example, for Red Hat Enterprise Linux, version 7,
use the /etc/security/limits.conf file. For Red Hat Enterprise
Linux, version 6, or AIX, use the
/etc/security/limits.d/90-nproc.conf file.
relayUser soft nofile 60000
relayUser hard nofile 60000
relayUser soft nproc 65535
relayUser hard nproc 65535
Use
the name of the operating system user that is running the agent relay for
relayUser. By default, the agent relay
installation program creates a user that is named agentrelay.
- Restart the computer that hosts the agent relay.
- To start the agent relay, go to the installation folder for the relay and run the
following command:
bin/agentrelay start
What to do next
If you must modify the relay, you can edit these properties
in the agentrelay.properties file in the relay_installation\conf directory.