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.

Also, as of this version, the communication between the Proxy Client and the Java communication process (JCP) uses TLS/SSL through a secure WebSocket (WSS). The JCP uses trusted certificates to prove its identity to other communication partners and requires a keystore to work with these certificates. Therefore, you have to install and configure the new Java communication process (JCP) and make sure you have the required certificates. For more information, see Installing the JCP and Types of Server Processes.

For more information about the different certificate types and for detailed instructions on how to create and use them, see What Kind of Certificates Should I Use for Automic Automation v21.

The Proxy Client requires a certificate to establish the connection to the JCP. You can use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters in the INI file of the Proxy Client to point to the relevant certificates. If the trustedCertFolder= parameter is not set, the certificates should be installed in the Java trust store. 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.
  
  Important! Do not use a certificate or key that is part of your company's key infrastructure, as the data is not verified at this point. After the connection is established, the parties use a negotiated secret key for symmetric encryption. Any malicious party that obtains the certificate after the connection is set up, is not able to decrypt the communication, as the symmetric key is random and renegotiated on each TLS/SSL connection setup.
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  
```
Use the trustedCertFolder=, agentSecurityFolder=, and keyPassword= parameters in the respective INI file to point to the relevant certificates. If the trustedCertFolder= parameter is not set, the certificates should be installed in the respective store; that is the Java trust store for Java Agents, the Windows OS store for Windows Agents, or the TLS/SSL store for UNIX Agents. For more information, see Securing Connections to the AE (TLS/SSL).

For more information about the different certificate types and for detailed instructions on how to create and use them, see What Kind of Certificates Should I Use for Automic Automation v21.
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).