Installing the Proxy

As a system administrator, you install the Proxy Client and Server. These installation instructions apply to Windows and UNIX.

Notes:

You must install the Proxy on each computer on which the Proxy Client or Server will run.
Check which Java version you require. For more information, see Compatibility Information.
Use the ServiceManager to start the Proxy Client and Server as a service. For more information, see ServiceManager.

This page includes the following:

Overview

The Proxy application allows administrators to combine the Java communication process (JCP) connections of the components of the Automation Engine (such as agents, AWI instances, APIs) into one connection and reverse the direction in which the connection was set up.

The connections between the Proxy Client and Server require TLS/SSL encryption and authentication (in pkcs12 format). These connections are only accepted if both have the same certificate. The TLS/SSL authentication cannot be deactivated.

As of version 21, the communication between the Proxy Client and the Java communication process (JCP) uses TLS/SSL server authentication - an industry standard - through a secure WebSocket (WSS). The JCP uses trusted certificates to prove their identity to other communication partners.

Therefore, you have to decide which kind of certificates you are going to use to secure the communication in your system. This decision must be considered carefully, as it determines not only how secure the connections are but also the time and effort you have to invest in renewing and deploying the certificates.

For more information, see TLS/SSL Considerations for Automic Automation .

When you used certificates signed by a CA, the certificates are stored in the respective Java or OS store by default. In this case, you only have to check that the root certificates already are in the respective store.

If you do not want to use the default location for this component, make sure you use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters (if applicable) in the respective configuration (INI) file to define the path to the folder where the trusted certificates are stored.

For more information, see Securing Connections to the AE (TLS/SSL).

The Proxy Server requires its own certificate which is then passed on to the folder where the trusted certificates for the respective agent are stored. This path is defined in the trustedCertFolder= parameter of the respective agent INI file.

Installation Procedure

Install Java Standard Edition. You can skip this step if the required version of Java Standard Edition is already available.

Use the following command to check the current version of your system's Java Virtual Machine (VM):

java -version

Note: The order of the indicated directories is relevant when specifying %PATH% or $PATH if several versions of JRE or Java SDK are installed on your computer. The Java Runtime Environment listed first is used.
Create a dedicated directory for the Proxy Server and another dedicated directory for the Proxy Client (for example, in Windows, C:\Automic\Proxy\bin) and copy the delivered files into the respective directory.

Important! Copy the INI file only to the Proxy Client directory. The Proxy Server does not require an INI file. For more information, see Proxy INI file.
Create the TLS/SSL certificate in pkcs12 format for the Proxy Server. This certificate is used for the communication between the Proxy Server and the Proxy Client.
1. Use the Java keytool in the bin folder of the Java program directory to create a self-signed certificate.
2. The following command creates the keystore.p12 file that saves a certificate, which is valid for 365 days. The KeyStore file is protected by the password passwd.
3. Enter the company information.
Start the Proxy Server (instance running on the agent, API, etc.) using the following command line parameters:
- servicePort= Port of the Proxy Server to which the Proxy Client connects. If this parameter is not specified, the default port 4321 is automatically used.
- keyStore= Path and name of the Keystore file
- keyStorePwd= Keystore file password
Example

java -cp proxy.jar com.uc4.proxy.Server -keyStore=keystore.p12 -keyStorePwd=passwd -servicePort=4321

Optionally, you can also use the command line to define the following parameters for the Proxy Server:

java -jar com.automic.proxy.server.ProxyServer
- --certAlias <arg>: Certificate alias
  
  Default:selfsigned
- --helpLib <arg>: Path to the message text library
  
  Default:./uc.msl
- --keyPwd <arg>: Key password
- --keyStore <arg>: Path to the keystore
- --keyStorePwd <arg>: Keystore password
- --log <arg>: Path to the log file used for logging output
- --logCount <arg>: Maximal number of log files used as history
- --serviceAddr <arg>: Locale IP address. It allows you to bind the Proxy Server to a particular interface
- --servicePort <arg>: TCP/IP port the Proxy Server uses to listen for the Proxy Client
  
  Default: 4321
- --trace <arg>: Path to the log file used for logging output
- --traceLevel <arg>: Level of trace output
  
  Allowed values: 0 - 9
The Proxy Client requires a certificate to connect to the Proxy Server and another one to connect to the JCP in the Automation Engine. Make sure you have both certificates in place.

Export the certificate of the Proxy Server from the keystore and copy it to the Proxy Client host. You can use the following command to export the certificate:
```
keytool -export
        -keystore KEYSTORE.p12 
        -alias jetty 
        -file proxy.cer  
```
When you used certificates signed by a CA, the certificates are stored in the respective Java or OS store by default. In this case, you only have to check that the root certificates already are in the respective store.

If you do not want to use the default location for this component, make sure you use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters (if applicable) in the respective configuration (INI) file to define the path to the folder where the trusted certificates are stored.

For more information, see Securing Connections to the AE (TLS/SSL).
Configure the INI file of the Proxy Client.
- In the [GLOBAL] section, define the server (Proxy Server) and routing ports:
  - serverProxy=4321
  - routingPort=2217
- Optionally, link Proxy pairs using the [OTHER_SP_LIST] section or define Proxy segments using the segment= parameter in the [GLOBAL] section of the INI file. For more information, see About Proxy.
Start the Proxy Client as an agent without entering command line parameters.

Example

java -jar proxy.jar

If no other location has been specified, the INI file is located in the same directory as the JAR file of the Proxy. Use the parameter -I to store the INI file in a different location.

Example

java -jar proxy.jar -Imy_proxy.ini

Upon starting, the Proxy Client creates a log file and tries to establish a connection to a Java communication process (JCP). If the connection to the JCP is successful, the Proxy Client connects to the Proxy Server.

Note: Starting the Proxy Client results in a technical connection to the AE system. This means that the Proxy Client connects as an agent to the AE system and the respective Java communication process (JCP). All Proxy Clients that are online are visible on the Agent page in the Administration perspective.
Configure the INI file of the Agent, which is connected over the Proxy. For more information, see Agents.
- In the [TCP/IP] section, define the connection endpoint, pointing to the Proxy Server and routing port:
  
  connection=proxy-server:routingPort
- The JCPLIST section must be either left empty or it must contain the connection information of other Proxy Servers:
  
  JCPLIST
  - JCP1=https://proxy-server1:port
  - JCP2=https://proxy-server2:port
Additionally, the Agent requires the certificate of the Proxy Server, instead of the certificate of the Java communication process (JCP).