Installing the TLS Gateway

As a system administrator, you install the TLS Gateway to facilitate the file transfer between TLS/SSL and non-TLS/SSL Agents and/or provide a communication process (CP) port, if needed.

Important! Check Broadcom Software Academy. There is a course available for this topic. For more information, see the Education section at the end of this topic.

This page includes the following:

Connecting to the Automation Engine

The TLS Gateway and the Automation Engine communicate using TLS/SSL and establish a connection with the Java communication process (JCP), which uses trusted certificates to prove their identity to other communication partners.

Important! Make sure you are familiar with the TLS/SSL and certificate implementation before installing and/or upgrading the respective component. For more information, see:

When you used certificates signed by a CA, the certificates are stored in the respective Java or OS store by default; that is the Java trust store for Java components and Java Agents, the Windows OS store for Windows Agents, or the TLS/SSL store for UNIX Agents. In this case, you only have to check that the root certificates already are in the respective store.

If the relevant certificates are not there and you want to import them, you can use OS or Java specific tools for that purpose, such as Keytool, cert-manager, OpenSSL and such. For more information on how to use those tools, please refer to the respective product documentation.

If you do not want to use the default locations for the components and Agents listed above, 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.

Important! TLS/SSL Agents (in containers and on-premises) as well as the TLS Gateway, when used for the Automic Automation Kubernetes Edition, establish a connection to an ingress / HTTPS load balancer, which requires a certificate for authentication.

Make sure that address of the load balancer is defined on both sides: the Automation Engine and the Agent / TLS Gateway and that your HTTPS load balancer has the required certificates in place. For more information, see Connecting to AWI, the JCP and REST Processes Using an Ingress.

Installing the TLS Gateway

The TLS Gateway is an Agent (HOST) object. The installation process is the same as for any other Agent (HOST) object.

You can create a new TLS Gateway and download a pre-configured TLS Gateway in Client 0 in the Process Assembly perspective.

You can also do the same in directly from the Administration perspective in any Client in the system. However, the TLS Gateway object is always also available in Client 0. When you download a pre-configured TLS Gateway, you don not have to make any additional definitions. However, you can change them as needed in Client 0.

Prerequisite! The Packs required for a Centralized Agent Upgrade (CAU) must be installed before you can download an Agent from the Administration perspective. You can download the CAU packs from https://marketplace.automic.com/. Once you have downloaded them, you have to install them in Client 0. You can do so from the Packs page in the Administration perspective. For more information, see Centralized Agent Upgrade (CAU).

Java Cryptography Extension (JCE)

To ensure that the TLS Gateway can handle non-TLS/SSL connections, the JCP must have the Java Cryptography Extension installed.

Important! JDK requires these policy files only if you work with Java 8. Java 9 and later versions include and use these files by default.

  1. Install Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy.

    The JCE Unlimited Strength Jurisdiction Policy has to be installed on the machines where:

    • The Automic Web Interface runs.
    • The Automation Engine (JWP/JCP) runs.

    Download at Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy

    For IBM Java, you must use the policy files of IBM. The unlimited jurisdiction policy files are located in directory SDK /demo/jce/policy-files/unrestricted/. For more information, see https://www.ibm.com/support/knowledgecenter/en/SSYKE2_7.1.0/com.ibm.java.security.component.71.doc/security-component/sdkpolicyfiles.html.

    The Readme file contains the installation instructions on how to copy the .jar files to appropriate location (e.g. <java-home>\lib\security). If there are multiple Java installations on the same computer, setting up a policy file for all installations is recommended.

For more information, see Installing the JCP .

Adding a TLS Gateway - Process Assembly

You can create a TLS Gateway Agent object manually in Client 0 in the Process Assembly perspective.

  1. You have two options:

    • Right-click anywhere on the list and select Add > Add Object.
    • Click the Add Object button on the toolbar

  2. On the Add Object dialog, click the Agent (AGENT) object type to access the list of available agent objects.

  3. Select the TLS-GATEWAY Agent and click the Add button. The Object Name dialog is displayed.

  4. Enter a descriptive Name.

  5. Optionally, enter a short and descriptive Title that helps you recognize the purpose of the object.

  6. Click OK.

A new page opens where you can start with the object definitions in AWI. For more information, see Configuring the Agent Properties.

You can also download the TLS Gateway from the Process Assembly perspective, see Downloading a TLS Gateway.

Adding a TLS Gateway - Administration Perspective

To add a TLS Gateway, do the following:

  1. Open the Administration perspective and select Agents & Groups > Agents from the navigation pane on the left.

  2. You have two options:

    • Right-click anywhere on the list and select Add > Add Agent

    • Click the Add Agent button on the toolbar

  3. Select the TLS Gateway Agent type from the list and click the Add button. The Object Name dialog is displayed.

  4. Enter a descriptive Name.

  5. Optionally, enter a short and descriptive Title that helps you recognize the TLS Gateway.

  6. Click OK.

The new TLS Gateway is available in the Agents list and can be downloaded, see Downloading a TLS Gateway.

For more information on how to edit the TLS Gateway definition in AWI, see Configuring the Agent Properties.

Downloading a TLS Gateway

Prerequisite! The Packs required for a Centralized Agent Upgrade (CAU) must be installed before you can download an Agent from the Administration perspective. You can download the CAU packs from https://marketplace.automic.com/. Once you have downloaded them, you have to install them in Client 0. You can do so from the Packs page in the Administration perspective. For more information, see Centralized Agent Upgrade (CAU).

You can download a TLS Gateway either in the Process Assembly or in the Administration perspective. To do so, you have to locate the relevant TLS Gateway either in the folder in which you placed it in the Process Assembly or on the Agents list on the Administration perspective.

  1. Once you have located the relevant TLS Gateway, you have two options:

    • Select the TLS Gateway and click the Download Agent button on the toolbar

    • Right-click the TLS Gateway and select Download Agent

    The Download Agent dialog is displayed. The Name field is populated automatically.

  2. Define the corresponding Operating System and Architecture.

  3. Once you have defined all parameters, click Download. Your browser notification shows the TLS Gateway.zip file is being downloaded.

  4. Unpack the .zip file on the same machine on which the TLS Gateway runs.

  5. Once the file is unpacked, you can define the relevant ports in the [TCP/IP] section of the INI file of the TLS Gateway:

    • tls_port= and gss_port=

      Source and destination Agent ports used for the file transfer between TLS/SSL and non-TLS/SSL Agents.

    • cp_port=

      Communication process (CP) port used by non-TLS/SSL Agents if this option has been activated in the TLS_GATEWAY_CP variable.

    Optionally, if you are using Net Areas, you can define them using the NetArea= parameter in the [TCP/IP] section of the INI file of the TLS Gateway.

    More information:

  6. Run the *.jar binary file to start the TLS Gateway.

    The downloaded TLS Gateway is ready to work.

Renaming/Deleting a TLS Gateway

You can rename and/or delete a TLS Gateway from the Agents list in any Client that you have access to, given the following applies:

  • You have write (W) permissions on the TLS Gateway
  • The TLS Gateway is inactive
  • The TLS Gateway is not used in multiple Clients

Note: If you try to rename or delete a TLS Gateway that is used in multiple Clients, an error message is displayed.

To rename and/or delete a TLS Gateway, right-click it and select Rename/Delete.

Using Scripts

You can use scripts to easily create, download and extract TLS Gateway packs, as well as start them.

We have gathered a number of deployment script examples for the TLS Gateway. They allow you to deploy and start the TLS Gateway without having to create your own script. You can also merge separate scripts used in the examples into one large script.

More information:

Upgrading a TLS Gateway

You can use the Centralized Agent Upgrade (CAU) to upgrade your TLS Gateway instances to a different version. However, because of the high availability required for file transfers, it is not recommended to upgrade them all at the same time. For more information, see Centralized Agent Upgrade (CAU).

Education

The Broadcom Software Academy provides a wide range of free online trainings. For information about how to navigate through the Academy and on how to register for courses, see Free Online Courses.

The following course(s) are associated with this topic:

Automic Automation TLS Gateway

See also: