7. Transports¶
The Transports
element configures how AMPS communicates with
publishers and subscribers, as well as how AMPS accepts connections for
replication. The Transports element is a container for one or more
Transport
elements. Each Transport
is a combination of a network
transport, an AMPS header protocol, and a message type.
A Transport
also specifies the Authentication
used to validate
the users that connect, and the Entitlement
used to enforce
permissions for users that connect over that transport.
AMPS supports a variety of network transports, header protocols and
message formats for communication between publishers and subscribers.
This section describes how to configure a Transport
.
Element | Description | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Name
|
The name to use for this Transport. This name appears in the AMPS log for messages related to the transport. There is no default for this value. When the |
||||||||||||||||||
Protocol
|
This element defines the protocol to use for sending and receiving messages. The
protocol is typically AMPS provides support for the following protocols:
60East recommends using the Older versions of AMPS used message headers in the same format as the message type:
if your instance supports applications that expect to use a specific message type
protocol, use that protocol in your |
||||||||||||||||||
Type
|
The type of Transport. Valid values include:
|
||||||||||||||||||
InetAddr |
The port on which AMPS will listen for this transport. This element can also specify an IP address, in which case AMPS listens only on that address. If no IP address is specified, AMPS listens on all available addresses. This element is not required for transports of the |
||||||||||||||||||
MessageType |
Restricts a transport to a single message type. When provided, AMPS assumes that all
connections to this transport use the specified When the When present, this is a reference to the name of a specific message type defined in
the In this release, AMPS loads the following message types by default: A Important: A |
||||||||||||||||||
Default: When the |
|||||||||||||||||||
InitialState |
Defines whether, when AMPS starts, the transport is enabled or disabled. When the
transport is disabled, AMPS does not listen for or accept connections on the
transport. When This configuration option can be useful for defining a transport that is only available when certain conditions are true: for example, an instance might start with the connection used by clients disabled, and let an external monitoring system enable the connection during business hours and disable the connection outside of business hours. Default: |
||||||||||||||||||
Entitlement |
Specifies the entitlement module to use for this transport. If no entitlement module
is provided, the transport uses the default entitlement module for the instance. This
element must contain a Default: The module specified in the |
||||||||||||||||||
Authentication |
Specifies the authentication module to use for this transport. If no authentication
module is provided, the transport uses the authentication module for the instance.
This element must contain a Default: The module specified in the |
||||||||||||||||||
MessageMemoryLimit |
The total amount of memory to allocate to messages before offlining clients. Default: The setting configured at the instance level. If this option is not
specifically set at the instance level, the instance defaults to 10% of total host
memory or 10% of the amount of host memory AMPS is allowed to consume (as reported by
This option is specified in bytes, and accepts the standard AMPS notation
(for example, |
||||||||||||||||||
MessageDiskLimit |
The total amount of disk space to allocate to messages before disconnecting clients. Default: The setting configured at the instance level. If this option is not specifically set at the instance level, the instance defaults to 1GB or the amount specified in the MessageMemoryLimit, whichever is highest. This option is specified in bytes, and accepts the standard AMPS notation
(for example, |
||||||||||||||||||
MessageDiskPath |
The path to use to write offline files. Default: |
||||||||||||||||||
TransportFilter |
A transport filter to use for the transport. When specified, each command received over this transport is provided to the filter. This element requires a A transport can specify multiple filters. When multiple filters are specified, AMPS provides the command to each specified filter, in the order in which the filters appear in the transaction log. There is no default for this element. If no |
||||||||||||||||||
ClientMessageAgeLimit |
The maximum amount of time for the client to lag behind. If a message for the client
has been held longer than this time, the client will be disconnected. This parameter
is an AMPS time interval (for example, Default: No age limit, or the setting configured at the instance level |
||||||||||||||||||
ClientMaxCapacity |
The amount of available capacity a single client can consume. Before a client is
offlined, this limit applies to the Default: |
Table 7.1: Transport Parameters
Starting with 5.1, AMPS supports encrypting client connections using the
SSL (Secure Sockets Layer) network protocol. The following parameters
apply to transports that use SSL. While AMPS performs additional
configuration validation if the transport is configured with a Type
of tcps
, if a Certificate
and PrivateKey
are specified for a
Transport
of tcp
type, AMPS will use SSL for that Transport
.
These options also apply to transports of type amps-replication-secure
.
Element | Description |
---|---|
Certificate
|
The certificate file to use for the server. Default: There is no default for this option. |
PrivateKey
|
The private key to use for the server. Default: There is no default for this option. |
Ciphers |
The cipher list to use for this transport. The cipher list is passed to the OpenSSL implementation without being interpreted by the AMPS server. Default: There is no default for this option. For OpenSSL, details on the format of the cipher list are available at https://www.openssl.org/docs/man1.1.0/apps/ciphers.html |
Table 7.2: SSL Transport Parameters
For protocols of Type
amps-unix
, AMPS requires the following
additional configuration option:
Element | Description |
---|---|
FileName
|
Specifies the location on the filesystem where the Unix-domain socket will be created. This location is the path that will be provided to clients that need to connect using this transport. This element is required for transports of type
|
Table 7.3: Transport Parameters
For protocols of Type
websocket
, AMPS supports the following
additional configuration option:
Element | Description |
---|---|
PerMessageDeflate |
Controls per-message deflation for websocket connections. When this value is Per-message deflation is normally negotiated between an application and AMPS during the opening handshake of a websocket connection. 60East recommends leaving this option enabled unless you have a specific reason for disabling it. Default: |
Table 7.4: Websocket Transport Parameters
Configuring Slow Client Offlining¶
<AMPSConfig>
...
<MessageMemoryLimit>10GB</MessageMemoryLimit>
<MessageDiskPath>/mnt/fastio/AMPS/offline</MessageDiskPath>
<ClientMessageAgeLimit>30s</ClientMessageAgeLimit>
...
<Transports>
<!-- This transport shares the 10GB MessageMemoryLimit
defined for the instance. -->
<Transport>
<Name>regular-json-tcp</Name>
<Type>tcp</Type>
<InetAddr>9007</InetAddr>
<MessageType>json</MessageType>
</Transport>
<!-- This transport shares the 10GB MessageMemoryLimit
defined for the instance. -->
<Transport>
<Name>regular-bson-tcp</Name>
<Type>tcp</Type>
<InetAddr>9010</InetAddr>
<MessageType>bson</MessageType>
<!-- However, this transport does not allow clients to fall as far behind as the
instance-level setting -->
<ClientMessageAgeLimit>15s</ClientMessageAgeLimit>
</Transport>
<!-- This transport has a separate 35GB MessageMemoryLimit
and a 70GB MessageDiskLimit. It uses the instance-wide
30s parameter for the ClientMessageAgeLimit -->
<Transport>
<Name>highpri-json-tcp</Name>
<Type>tcp</Type>
<InetAddr>9995</InetAddr>
<MessageType>json</MessageType>
<MessageMemoryLimit>35GB</MessageMemoryLimit>
<MessageDiskLimit>70GB</MessageDiskLimit>
</Transport>
</Transports>
</AMPSConfig>
Example 7.1: Slow Client Management Configuration Example
<AMPSConfig>
...
<MessageMemoryLimit>10GB</MessageMemoryLimit>
<MessageDiskPath>/mnt/fastio/AMPS/offline</MessageDiskPath>
<ClientMessageAgeLimit>30s</ClientMessageAgeLimit>
...
<Transports>
<!-- This transport shares the 10GB MessageMemoryLimit
defined for the instance. -->
<Transport>
<Name>regular-json-tcp</Name>
<Type>tcp</Type>
<InetAddr>9007</InetAddr>
<MessageType>json</MessageType>
</Transport>
<!-- This transport shares the 10GB MessageMemoryLimit
defined for the instance. -->
<Transport>
<Name>regular-bson-tcp</Name>
<Type>tcp</Type>
<InetAddr>9010</InetAddr>
<MessageType>bson</MessageType>
<!-- However, this transport does not allow clients to fall as far behind as the
instance-level setting -->
<ClientMessageAgeLimit>15s</ClientMessageAgeLimit>
</Transport>
<!-- This transport has a separate 35GB MessageMemoryLimit
and a 70GB MessageDiskLimit. It uses the instance-wide
30s parameter for the ClientMessageAgeLimit -->
<Transport>
<Name>highpri-json-tcp</Name>
<Type>tcp</Type>
<InetAddr>9995</InetAddr>
<MessageType>json</MessageType>
<MessageMemoryLimit>35GB</MessageMemoryLimit>
<MessageDiskLimit>70GB</MessageDiskLimit>
</Transport>
</Transports>
</AMPSConfig>
Example 7.2: Transports Example with Resource Management
<AMPSConfig>
<Transports>
<Transport>
<Name>translate-legacy-topics</Name>
<Type>tcp</Type>
<InetAddr>9017</InetAddr>
<Protocol>amps</Protocol>
<TransportFilter>
<Module>amps-topic-translator</Module>
<Options>
<Topic>orders_for_northamerica:NAOrders</Topic>
<Topic>catalog_items:Catalog</Topic>
<Topic>customer_.*:Customers</Topic>
</Options>
</TransportFilter>
</Transport>
</Transports>
</AMPSConfig>
Example 7.3: Transport Filter Example
<AMPSConfig>
<Transports>
<Transport>
<Name>ssl-all-message-types</Name>
<Type>tcps</Type>
<InetAddr>9007</InetAddr>
<Protocol>amps</Protocol>
<Certificate>${AMPS_INSTALL}/cert.pem</Certificate>
<PrivateKey>${AMPS_INSTALL}/key.pem</PrivateKey>
<Ciphers>HIGH:!aNULL</Ciphers>
</Transport>
</Transports>
</AMPSConfig>
Example 7.4: SSL Transport Example