Bridge

Overview

The Bridge is a component that helps integrate DirX Access Server according to the DirX Access Blueprint where the DirX Access WebApplications container used to take its place.

The Bridge takes advantage of the third party ProxyServlet.Transparent which is wrapped in a web application and is able to forward the load to a specific port. This results in the fact that several such web applications hosted on a standard Jetty web server are needed to fully replace the former DirX Access WebApplication container. The Bridge is also intended to forward the load to single DirX Access server instance. There is no intention for load balancing or failover.

Architecture

HLA Bridge Architecture
Figure 1. HLA Bridge Architecture

Figure 1 shows the relationships between the Bridge and its nearest components. Namely, following features:

  • If DXA Bridge component shall be in place, each DXA Server requires its own deployed DXA Bridge (as its routing is dependent on the ports, not on the server address).

  • Even if they proxy the communication to the same cluster of DXA Servers, the DXA Bridges don’t need to be configured the same - rather, their configuration is dependent on the configuration of the port assignments of corresponding DXA Servers.

  • There is a one-to-one mapping between open ports at the DXA Server (that shall be accessible by the Load balancer) and open ports at corresponding DXA Bridge.

Prerequisite

Since the Bridge only forwards the load, we need to have intended targets (exposed ports on the DirX Access Server) already configured. Please follow the Port Assignments document for more information.

Installation

Installation of DirX Access creates a template folder for DXA Bridge in {installation_directory}/Services/templates/bridge. To install new Bridge, following actions have to be performed:

  1. Copy and rename the {installation_directory}/Services/templates/bridge folder into the desired place of the new Bridge instance. (Furthermore, we will reference the desired place as {bridge_installation_directory}). It is recommended to keep the {bridge_installation_directory}/jetty-home-VERSION and {bridge_installation_directory}/jetty-base folders strictly separated and the {bridge_installation_directory}/jetty-home-VERSION folder as read-only for easy future upgrade.

  2. The {bridge_installation_directory}/jetty-base folder contains one plain and two SSL inbound connectors/ports preconfigured but commented out. It is necessary to enable as many inbound connectors as there are exposed ports on the DirX Access Server. The meaning of the listed properties and variables is explained in the Configuration.

    1. Plain port enablement

      1. In the {bridge_installation_directory}/jetty-base/etc/jetty-httpd.xml file, uncomment the <Call name="addConnector"> section with id="httpConnector".

      2. In the {bridge_installation_directory}/jetty-base/start.d/httpd.ini file, uncomment and fill in the ${httpConnectorPort} and ${httpConnectorName} variables.

    2. SSL port enablement

      1. In the {bridge_installation_directory}/jetty-base/etc/jetty-ssl.xml file, uncomment the <Call name="addConnector"> section with id="sslConnector".

      2. In the {bridge_installation_directory}/jetty-base/start.d/ssl.ini file, uncomment and fill in the ${sslConnectorPort} and ${sslConnectorName} variables.

      3. Please notice the referenced id="sslContextFactory".

    3. Second SSL port enablement

      1. In the {bridge_installation_directory}/jetty-base/etc/jetty-ssl.xml file, uncomment the <Call name="addConnector"> section with id="sslConnector2".

      2. In the {bridge_installation_directory}/jetty-base/start.d/ssl.ini file, uncomment and fill in the ${sslConnector2Port} and ${sslConnector2Name} variables.

    4. In case more inbound ports are needed

      1. In the respective xml file, copy the <Call name="addConnector"> section and select different id,name and port properties of the connector.

      2. In the respective ini file, use the properties from the previous point to place port and name of the new connector.

  3. The {bridge_installation_directory}/jetty-base folder does not contain any outbound connection (any ProxyServlet.Transparent web application) to the exposed port of the DirX Access Server. The outbound connections have to be created and assigned to the inbound connectors via Virtual Hosts.

    1. Semi-automatic configuration

      1. The Direct Application of System Actions and Configuration or SysActions RESTful Web Service is able to create the web applications and web application contexts of for all outbound connections based on the already configured ports on the DirX Access Server.

      2. Apply the dxaDeployBridge system action template.

        1. Fill in the template and place it to the {installation_folder}/Services/instances/{instance}/startup/sysactions/ folder.

        2. Restart the DirX Access Server.

        3. After successful application, the template should be moved to the {installation_folder}/Services/instances/{instance}/startup/sysactions/used/ folder.

        4. The resulting archive should be found in the specified target in the template.

      3. Check the archive. The archive should contain web application context files ({webappname}-webapp.xml files in jetty-base/etc/application folder) and web applications ({webappname}.war files in jetty-base/webapps folder)

        1. Check that each web application context file contains exactly one reference to the inbound connector name (virtualHosts parameter).

      4. Unzip the content to the {bridge_installation_directory}/jetty-base folder.

    2. Manual configuration

      1. Installation of DirX Access creates a template of the dirx.access.bridge.web web application in {installation_folder}/Services/templates/webapps/bridge.

      2. Fill in the mandatory parameter proxyTo in the WEB-INF\web.xml file.

      3. For each exposed port on the DirX Access Server, insert the web application into the {bridge_installation_directory}/jetty-base/webapps folder as war file.

      4. For each web application, create the web application context file ({webappname}-webapp.xml) in the {bridge_installation_directory}/jetty-base/etc/applications folder.

        • The example shows the web application context of the web application of the connection to the https://my-server1.my-company.example address and the 11115 port of the DirX Access Server.

          <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure.dtd">
<Configure class="org.eclipse.jetty.webapp.WebAppContext">
    <Set name="contextPath">/</Set>
    <Set name="war">webapps\connectorTo11115.war</Set>
    <Set name="virtualHosts">
        <Array type="java.lang.String">
            <Item>@connectorTo11115</Item>
        </Array>
    </Set>
</Configure>

        • Please mind the virtualHosts configuration. Each web application should have one virtualHost and the virtualHost in this case refers to the connector with the connectorTo11115 name.

  4. The Bridge needs the latest version of JAVA11 to run. Install it and set it to JAVA_HOME and PATH environment variable.

Configuration

The section describes the meaning of the already listed variables.

Variable

Location in Bridge/jetty-base folder

Default

Description

${httpConnectorPort}

etc/http.ini

11914

The value of the port on which the plain connector with id="httpConnector" listens on.

${httpConnectorName}

etc/http.ini

connectorTo11114

The name value of the plain connector with id="httpConnector". The name is used as a reference to associate the web application with the connector through Virtual Hosts.

${sslConnectorPort}

etc/ssl.ini

11915

The value of the port on which the SSL connector with id="sslConnector" and SSL context factory with id="sslContextFactory" listens on.

${sslConnectorName}

etc/ssl.ini

connectorTo11115

The name value of the SSL connector with id="sslConnector". The name is used as a reference to associate the web application with the connector through Virtual Hosts.

${sslContextFactoryKeyStorePath}

etc/ssl.ini

etc/keystore.p12

The KeyStore file path (relative to {bridge_installation_directory}/jetty-base folder) of the id="sslContextFactory".

${sslContextFactoryTrustStorePath}

etc/ssl.ini

The TrustStore file path (relative to {bridge_installation_directory}/jetty-base folder) of the id="sslContextFactory".

${sslContextFactoryKeyStorePassword}

etc/ssl.ini

The KeyStore password.

${sslContextFactoryTrustStorePassword}

etc/ssl.ini

The TrustStore password.

proxyTo

webapps/{connTo}.war/WEB-INF/web.xml

https://domainname:port

The address including the port where to forward the load.

jetty.deploy.monitoredDir

etc/deploy.ini

etc/applications

Monitored directory name (relative to {bridge_installation_directory}/jetty-base folder).

virtualHosts

etc/applications/{connTo}-webapp.xml

The name of the connector to be assigned to the web application to which the webapplication context belongs.

The descriptions of the optional parameters can be found:

Running a Bridge from the Command Line

The Bridge can be started from the command line in the same way as a standard Jetty web server Jetty 11 Operations Guide – Getting Started

Start the Bridge by running the following command:

{bridge_installation_directory}\jetty-base> java -jar ..\jetty-home-11.0.13\start.jar

Bridge as a Windows Service

The Bridge can be run as a Windows Service. There is the possibility to use the prunsrv tool to create the Windows Service.

Install the Windows service by executing the command:

{bridge_installation_directory}\jetty-base\bin>serviceInstall.bat %SERVICE_NAME% %DISPLAY_NAME% %JETTY_HOME% %JETTY_BASE% %JAVA_HOME% %STOP_PORT%

, where:

  1. %SERVICE_NAME% is the windows service identifier,

  2. %DISPLAY_NAME% is the windows service display name,

  3. %JETTY_HOME% is the absolute path to jetty-home-VERSION,

  4. %JETTY_BASE% is the absolute path to jetty-base,

  5. %JAVA_HOME% is the absolute path to preinstalled JAVA11,

  6. %STOP_PORT% is the stopping port of the Jetty Web Server

E.g.,

{bridge_installation_directory}\jetty-base\bin\serviceInstall.bat DirXAccessBridgeMy-Company "DirX Access Bridge My-Company" "{bridge_installation_directory}\jetty-home-11.0.13" "{bridge_installation_directory}\jetty-base" "%ProgramFiles%\Java\jdk-11.0.16.1" 11981

JAVA Runtime Library Update

The Java runtime library can be updated without reinstalling the Windows Service.

The prunsrv tool must be used directly to this purpose:

{bridge_installation_directory}\jetty-base\bin>prunsrv.exe //US//%SERVICE_NAME% --JavaHome="%JETTY_HOME%"

, where:

  1. %SERVICE_NAME% is the windows service identifier,

  2. %JAVA_HOME% is the absolute path to the new preinstalled JAVA11

E.g.,

{bridge_installation_directory}\jetty-base\bin\prunsrv.exe //US//DirXAccessBridgeMy-Company --JavaHome="%ProgramFiles%\Java\jdk-11"

Using the JAVA_HOME

There is possibility to use the JAVA_HOME environment variable only. All references to the JAVA_HOME parameter must be removed from the {bridge_installation_directory}\jetty-base\bin\serviceInstall.bat script and the windows service must be reinstalled.