Skip to content
Connect > Gateway

Gateway Configuration

This page lists the configuration properties that control the Gateway listeners, security, routing, logging, and identifier allocation.

Overview

Gateway properties fall into 6 groups. The native listener and the JDBC listener each take their own network and TLS properties, so the 2 are configured and secured independently. A security group covers the authorized-clients lists, the authentication plugin, and the entitlement filter plugin. The remaining groups control the routes file and state, logging output, and identifier allocation.

Set overrides in config/local.properties. Properties shown as not set are declared by the Gateway but carry no value in the shipped defaults; the Gateway supplies its own behavior when they are absent.

Native listener

ami.gateway.port

Default:
1
ami.gateway.port=3406
Description:
  • The port the native listener binds to. Serves client libraries.

ami.gateway.port.bindaddr

Default:
Not set.
Description:
  • The local address the native listener binds to.
  • Set this to restrict the listener to one interface on a multi-homed host.

ami.gateway.port.whitelist

Default:
Not set.
Description:
  • Client addresses permitted to connect to the native listener.

ami.gateway.ssl.keystore.file

Default:
1
ami.gateway.ssl.keystore.file=${ami.keyfile}
Description:
  • Keystore used to serve TLS on the native listener.
  • Resolves to the shared instance keystore (keys/3forge.jks) by default.
  • When a keystore is set, the listener enforces mutual TLS. See Security.

ami.gateway.ssl.keystore.password

Default:
1
ami.gateway.ssl.keystore.password=${ami.keypass}
Description:
  • Password for the native listener keystore.

JDBC listener

ami.gateway.jdbc.port

Default:
1
ami.gateway.jdbc.port=3407
Description:
  • The port the JDBC listener binds to. Clients connect here. See JDBC Access.

ami.gateway.jdbc.port.bindaddr

Default:
Not set.
Description:
  • The local address the JDBC listener binds to.

ami.gateway.jdbc.port.whitelist

Default:
Not set.
Description:
  • Client addresses permitted to connect to the JDBC listener.
  • Set independently of the native listener whitelist.

ami.gateway.jdbc.protocol.version

Default:
Not set. The Gateway uses protocol version 2 when this is not set.
Description:
  • Gates the JDBC execution path. Set to 0 to force the legacy query path.
  • This does not set the negotiated wire version. A connection negotiates the lower of the client and server versions, and the server version is fixed by the build. See JDBC Access.

ami.gateway.jdbc.ssl.keystore.file

Default:
1
ami.gateway.jdbc.ssl.keystore.file=${ami.keyfile}
Description:
  • Keystore used to serve TLS on the JDBC listener.

ami.gateway.jdbc.ssl.keystore.password

Default:
1
ami.gateway.jdbc.ssl.keystore.password=${ami.keypass}
Description:
  • Password for the JDBC listener keystore.

Security

The Gateway shares one authentication plugin across both listeners; there is no separate JDBC auth plugin property. See Security for how these properties combine into the admission model.

ami.gateway.ssl.authorized.clients.file

Default:
1
ami.gateway.ssl.authorized.clients.file=${ami.ssl.authorized.clients.file}
Description:
  • The authorized-clients list for the native listener, resolving to keys/3forge.auth by default.
  • When the native listener has a keystore, a client is admitted only if its certificate's public key is in this file.

ami.gateway.jdbc.ssl.authorized.clients.file

Default:
1
ami.gateway.jdbc.ssl.authorized.clients.file=${ami.ssl.authorized.clients.file}
Description:
  • The authorized-clients list for the JDBC listener, resolving to keys/3forge.auth by default.
  • Set independently of the native listener list.

ami.gateway.auth.plugin.class

Default:
1
ami.gateway.auth.plugin.class=${ami.auth.plugin.class}
Description:
  • The authentication plugin applied to both listeners, following the instance-wide ami.auth.plugin.class (default ACCESS_FILE) unless overridden.
  • When left blank, authentication is disabled and no login is required.

ami.gateway.filter.plugin.class

Default:
Not set.
Description:
  • The entitlement filter plugin applied to queries and subscriptions.
  • When not set, no filter is applied. See Security.

Routing and state

ami.gateway.routes.file

Default:
1
ami.gateway.routes.file=data/gateway.routes
Description:
  • The routes file defining reachable Centers.
  • Created with an example route if absent. See Routing.

ami.gateway.check.config.file.changes.period.ms

Default:
1
ami.gateway.check.config.file.changes.period.ms=2000
Description:
  • How often the Gateway checks its configuration files, including the routes file, for changes, in milliseconds.
  • Only routes that changed are restarted.
  • The 2000 ms value is a built-in fallback. The key is absent from the shipped defaults.properties, so searching the shipped configuration for it finds nothing. Set it explicitly to change the interval.

ami.gateway.persist.dir

Default:
Not set.
Description:
  • Directory holding persisted Gateway state.

ami.gateway.table.aliases

Default:
Not set.
Description:
  • Alternative names for tables reached through the Gateway, as a comma-separated list of source=target pairs: source=target,source=target,.... Whitespace around either side is ignored.
  • source is the table name a client writes in a FROM clause. target is the table actually queried on the route. Repeating a source maps it to several targets, and the query is sent to each and the results merged.
  • Set this on the AmiCore process, not on the Gateway component. The Gateway reads it from the host process configuration, so a value placed in the component's own config/local.properties is ignored without warning. The listener and TLS properties above behave the opposite way and are read from the component.
  • A malformed value stops the Gateway starting, with Property ami.gateway.table.aliases is invalid (Expecting source=target,source=target,...).

An alias must name a table that already exists on a route

The Gateway selects routes using the name as written, before the alias is applied, so an alias only works when its source is itself a real table on some route. Aliasing an invented name fails with GATEWAY: Table not found: <source>.

An alias also cannot be used in a join. A FROM naming more than one table, where any is an alias, returns GATEWAY: Table aliases in joins not currently supported.

Logging

ami.gateway.log.messages

Default:
Not set.
Description:
  • Whether messages passing through the Gateway are logged.
  • Enabling this on a busy Gateway produces substantial log volume.

ami.gateway.log.stats.period.millis

Default:
Not set.
Description:
  • How often Gateway statistics are written to the log, in milliseconds.

Identifier allocation

idfountain.path

Default:
1
idfountain.path=data/idfountain
Description:
  • File holding the identifier allocation state.

idfountain.batchsize

Default:
1
idfountain.batchsize=1000000
Description:
  • How many identifiers are reserved per allocation.