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.
- Please enter the directory where you would like to
install the agent relay.
- 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 IBM UrbanCode Deploy.
- Please enter your java home
- Specify the directory in which Java is
installed. Ensure that the JAVA_HOME environment
variable points to this directory.
- Enter the name of 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 or hostname which this Agent Relay should
use.
- Enter the IP address or host name on which the relay will listen.
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 which this Agent Relay should proxy
HTTP requests on.
- Enter the port on which the agent relay listens for HTTP requests
coming from agents. The default value is 20080.
- Enter the port which this Agent Relay should use for
communication.
- Enter the port that the agent relay uses for JMS-based communications
with remote agents. The default value is 7916.
- Connect the agent relay to a central server?
- Specify whether you want the relay to connect to the IBM UrbanCode Deploy server.
- Enter the IP or hostname of your central server.
- 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 the relay is connecting to clustered servers, specify the host
name of the load balancer. 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 port which the central server uses for communication.
- 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.
- Use mutual authentication between the agent, relay
and server.
- If mutual authentication is required, enter Y.
See SSL configuration for information about activating mutual authentication.
- Cache files on the relay which have been downloaded
by any connected agents?
- If you want to cache file on the agent relay, enter Y.
- Enter a list of statuses, one per line, or 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 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, using the following syntax: scheme://domain:port. For
example: https://myServer.com:8080.
- Please provide an authentication token for a 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.
- 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.
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.
To
start the agent relay, go to the installation folder for the relay
and run the following command:
bin/agentrelay start