Skip to content
Connect > Gateway

Gateway Quickstart

This guide starts a Gateway on a running 3forge instance and makes a first connection over each of its 2 listeners. The steps edit files under the installation root and run commands from the admin console; the console commands in this guide are entered at a live admin console prompt.

Prerequisites

  • A running 3forge Enterprise instance with at least one Center reachable.
  • Write access to the installation's data/ directory.
  • For the JDBC step, the JDBC driver available to the client, and a client certificate authorized for the JDBC listener. See JDBC Access.

Steps

  1. Add a Gateway component. Add this line to data/ami.components:

    1
    gateway;GATEWAY;.

    The line is name;type;pwd: an arbitrary unique name, the component type GATEWAY, and . for the process default working directory. The file is watched, so the Gateway launches without a restart.

  2. Confirm the routes file. On first start the Gateway creates data/gateway.routes if it is absent, containing one example route to the local Center:

    1
2
3
    # AmiGateway routes
# One route per line: id;host:port;certificateFile
local;localhost:3270;keys/3forge.pub

    Edit this file to point at the Centers the Gateway should reach. See Routing for the format and reload behavior.

  3. Connect over the JDBC listener. Using the JDBC driver, connect to the JDBC port (default 3407). Because the shipped Gateway configures a keystore, the connection uses mutual TLS, so supply the TLS options and a client certificate:

    1
    jdbc:amisql:localhost:3407?username=<user>&password=<password>&isSecure=true&sslKeystoreFile=<client-keystore>&sslKeystorePassword=<password>&sslPubFile=<server-public-key>

    Run a SELECT and confirm rows come back. A plain URL without the TLS options is refused on a default Gateway. See JDBC Access for the driver, the full option list, and the read-only and AMI-expression WHERE restrictions.

  4. Connect over the native listener. The native port speaks the same subscribe and query protocol a Center serves, so the Python and C++ client libraries reach it by pointing their subscription configuration at the Gateway instead of a Center:

    1
2
3
4
    import pyami.rt.ami_client as ac

node = ac.AmiCluster("N1", "<gateway-host>")
node.center_config = ac.AmiSubscriptionConfig("3406", True)

    1
2
    Cluster node("N1", "<gateway-host>");
node.subscription_config() = SubscriptionConfig("3406", /*ssl=*/true);

    A Gateway requires a username and password on that connection, where a Center reached directly can admit a client on its certificate alone. Client-side TLS options and the credential fields are covered in the client libraries documentation.

    For live data in a browser rather than a program, use the Web subscription path in Streaming. To run the route-management commands referenced above, see reaching the admin console in Routing.

Result

The Gateway runs as a component in the instance, its routes file points at the Centers it fronts, and a client can connect over both the native and JDBC listeners. From here:

  • Secure the listeners with mutual TLS and authentication: Security.
  • Manage routes without a restart: Routing.
  • Stream live, server-filtered data: Streaming.