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.

For more information on Transports, see the Transports section of the AMPS User Guide.

Element	Description
Name (required)	`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 Type of the Transport is amps-replication or amps-replication-secure, 60East recommends that the Name of the Transport match the value of the Type.
Protocol (required)	This element defines the protocol to use for sending and receiving messages. The protocol is typically amps, the name of a specific protocol for interoperability with another system or a legacy application, or the name of a custom protocol module specified in the Modules element. AMPS provides support for the following protocols: amps: Standard AMPS messaging, using compact headers in a JSON-based format. AMPS accepts json as a synonym for amps in a protocol declaration. websocket: Websocket protocol, using JSON format headers. AMPS also loads the following legacy protocols. These protocols are supported for backward compatibility. They will not be enhanced with new functionality, and do not provide all of the features of the above protocols. fix: Standard AMPS messaging, using headers in FIX format. fix-session: FIX session protocol, for use with systems that publish FIX. nvfix: Standard AMPS messaging, using headers in NVFIX format. soap: Standard AMPS messaging, using headers in SOAP format. xml: Standard AMPS messaging, using headers in XML format. 60East recommends using the amps protocol for general purpose AMPS messaging. When your application uses Javacript and web sockets, use the websocket protocol. 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 Transport configuration.
Type (required)	The type of Transport. Valid values include: tcp, tcps, amps-replication, amps-replication-secure, amps-unix tcp is the standard TCP transport. tcps is secure TCP transport: this transport type uses SSL and requires a certificate and private key to be set. amps-replication is for inbound replication connections. Notice that AMPS replication does not use the same transport type as other applications. amps-replication-secure is for inbound replication connections that use SSL. Notice that AMPS replication does not use the same transport type as other applications. This transport type requires a certificate and private key to be set. amps-unix is for incoming client connections over Unix domain sockets. This transport type requires a FileName, which is the location on the file system where the Unix domain socket will be created.
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. Starting with version 5.3.3, both IPv4 and IPv6 IP address formats are fully supported for use with specifying the network address of a transport. If no address is specified and the host supports IPv6, AMPS will listen for incoming connections on both IPv4 and IPv6 protocols. If you wish to limit AMPS to listen for addresses of only a specific IP protocol you may specify the ANY address for that protocol. For example: 0.0.0.0:9007 will cause AMPS to listen on port 9007 for only IPv4 addresses. [::]:9007 will cause AMPS to listen on port 9007 for only IPv6 addresses. This element is not required for transports of the amps-unix Type but is required for all other Type values.
MessageType	Restricts a transport to a single message type. When provided, AMPS assumes that all connections to this transport use the specified MessageType. If a different MessageType is provided in the connection string, AMPS refuses the connection. If no MessageType is provided in the connection string, AMPS accepts the connection and assumes that the connection uses the specified MessageType. When the Transport Type is amps-replication or amps-replication-secure, this element is ignored and the Transport accepts all message types configured in the instance. When present, this is a reference to the name of a specific message type defined in the MessageTypes section or one of the message types that AMPS loads by default. In this release, AMPS loads the following message types by default: fix, nvfix, xml, json, msgpack, bson, bflat and binary. Composite message types, and message types based on Google Protocol Buffers, must be defined in the MessageTypes element before they can be used. A Transport that uses the amps Protocol defaults to accepting all message types defined by the instance, and does not require setting a MessageType element. When the Transport does not specify a MessageType, the connecting client must declare the message type it will use when logging on. A Transport that uses the amps protocol can specify a single MessageType to accept by including this element. When a single MessageType is specified, AMPS does not require that the message type is specified by the client. Important: A Transport that uses one of the legacy Protocol values (fix, nvfix, or xml) must specify a MessageType. Default: When the Protocol is amps, defaults to accepting all message types defined by the instance. When the Protocol is one of the legacy values, there is no default and a MessageType must be provided.
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 InitialState is disabled, the transport must be explicitly enabled after startup (for example, through an action or the administrative console) for AMPS to listen for and accept connections on the transport. 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: enabled
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 Module element with the Name of an entitlement module. If the module requires options, those options are provided in an Options element within the Entitlement element. Default: The module specified in the Entitlement for the instance (defaults to amps-default-entitlement-module if not provided).
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 Module element with the Name of an authentication module. If the module requires options, those options are provided in an Options element within the Authentication element. Default: The module specified in the Authentication element for the instance (defaults to amps-default-authentication-module if not provided).
MessageMemoryLimit	The total amount of memory to allocate to messages before offlining clients for this transport. If this value is specified for the transport, AMPS will allow the specified amount of memory for connections to this transport, independent of the limits set for any other transports or the instance as a whole. 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 ulimit -m ), whichever is lowest. This option is specified in bytes, and accepts the standard AMPS notation (for example, 10GB or 250MB).
MessageDiskLimit	The total amount of disk space to allocate to messages before disconnecting clients. If this value is specified for the transport, AMPS will allow the specified amount of memory for connections to this transport, independent of the limits set for any other transports or the instance as a whole. 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, 10GB or 250MB).
MessageDiskPath	The path to use to write offline files. Default: /var/tmp, or the setting configured at the instance level
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 Module element, which contains the name of the module that provides the filter. This element may contain an Options element, which contains the set of options to provide to the module. The options required by a specific module depend on the module: see the documentation for the module for details. 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 TransportFilter is specified, AMPS processes commands exactly as they are received.
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, 30s for 30 seconds, or 1h for 1 hour). 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 MessageMemoryLimit. After a client is offlined, this limit includes the MessageDiskLimit. This parameter is a percentage of the total. Default: 50% (previous versions defaulted to100%).

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 (required for TLS/SSL connections)	The certificate file to use for the server. Default: There is no default for this option.
PrivateKey (required for TLS/SSL connections)	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.1/man1/ciphers.html
SecureSocketProtocols	The SSL/TLS protocols accepted by this Transport. This parameter accepts a space delimited list of values from the following list: SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3. Default: TLSv1.1 TLSv1.2 TLSv1.3 NOTE: 60East recommends using the default protocols unless there is a specific reason to enable earlier versions of the protocol and the security implications of the earlier protocols are well understood.
VerifyClient	Specifies whether the client is required to provide a certificate to be verified by the server. When this parameter set to True, at least one of CAFile or CAPath must be specified. Default: False
CAFile	Specifies a .pem file containing trusted certificates to be used to verify client certificates. There is no default for this parameter.
CAPath	Specifies a path to a directory containing .pem files containing trusted certificates to be used to verify client certificates. When this parameter is provided, and VerifyClient is set to True, AMPS will use every .pem file in that directory for verification. There is no default for this parameter.

For protocols of Type amps-unix, AMPS requires the following additional configuration option:

Element	Description
FileName (required for amps-unix transports)	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 amps-unix. There is no default.
FileMask	Specifies the file mask to use when creating the Unix-domain socket. The value of the mask is an octal number (by convention, four digits) in the same format as the standard umask command, and AMPS applies this mask exactly as the umask command would. The file is created with the user and group that the AMPS server process runs under. 0444 File is readable by owner, group, and any user. 0440 File is readable by owner and members of the owner's group. 0400 File is readable by owner only. 0664 File is readable and writable by owner and members of the owner's group. File is readable by any user. 0644 File is readable and writable by owner. File is readable by members of the owner's group and any user.

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 disabled, AMPS does not perform per-message deflation. If this option is not present, or is set to any other value, AMPS performs per-message deflation. 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: enabled
HTTPHeader	Specifies a header to be returned during the websocket handshake. This element can be specified any number of times. Every specified header will be returned. There is no default for this element.

Transports Example with Slow Client Management

<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-tcp</Name>
            <Type>tcp</Type>
            <InetAddr>9007</InetAddr>
            <Protocol>amps</Protocol>
        </Transport>

        <!-- This transport shares the 10GB MessageMemoryLimit
            defined for the instance. -->
        <Transport>
            <Name>regular-websocket</Name>
            <Type>tcp</Type>
            <InetAddr>9008</InetAddr>
            <Protocol>websocket</Protocol>
        </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-tcp</Name>
            <Type>tcp</Type>
            <InetAddr>9995</InetAddr>
            <MessageMemoryLimit>35GB</MessageMemoryLimit>
            <MessageDiskLimit>70GB</MessageDiskLimit>
            <Protocol>amps</Protocol>
        </Transport>
    </Transports>
</AMPSConfig>

Transports Example with Transport Filter

<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>

TLS/SSL Transport 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>