Appendix A. Acceptor and Connector Configuration Parameters

The tables below detail some of the available parameters used to configure Netty network connections. Parameters and their values are appended to the URI of the connection string. See Network Connections: Acceptors and Connectors for more information. Each table lists the parameters by name and notes whether they can be used with acceptors or connectors or with both. You can use some parameters, for example, only with acceptors.

Note

All Netty parameters are defined in the class org.apache.activemq.artemis.core.remoting.impl.netty.TransportConstants. Source code is available for download on the customer portal. A valid Red Hat subscription is required.

Table A.1. Netty TCP Parameters

ParameterUse with…​Description

batchDelay

Both

Before writing packets to the acceptor or connector, the broker can be configured to batch up writes for a maximum of batchDelay milliseconds. This can increase overall throughput for very small messages. It does so at the expense of an increase in average latency for message transfer. The default value is 0 ms.

connectionsAllowed

Acceptors

Limits the number of connections that the acceptor will allow. When this limit is reached, a DEBUG-level message is issued to the log and the connection is refused. The type of client in use determines what happens when the connection is refused.

directDeliver

Both

When a message arrives on the server and is delivered to waiting consumers, by default, the delivery is done on the same thread as that on which the message arrived. This gives good latency in environments with relatively small messages and a small number of consumers, but at the cost of overall throughput and scalability - especially on multi-core machines. If you want the lowest latency and a possible reduction in throughput then you can use the default value for directDeliver, which is true. If you are willing to take some small extra hit on latency but want the highest throughput set directDeliver to false.

handshake-timeout

Acceptors

Prevents an unauthorized client to open a large number of connections and keep them open. Because each connection requires a file handle, it consumes resources that are then unavailable to other clients.

This timeout limits the amount of time a connection can consume resources without having been authenticated. After the connection is authenticated, you can use resource limit settings to limit resource consumption.

The default value is set to 10 seconds. You can set it to any other integer value. You can turn off this option by setting it to 0 or negative integer.

After you edit the timeout value, you must restart the broker.

localAddress

Connectors

Specifies which local address the client will use when connecting to the remote address. This is typically used in the Application Server or when running Embedded to control which address is used for outbound connections. If the local-address is not set then the connector will use any local address available.

localPort

Connectors

Specifies which local port the client will use when connecting to the remote address. This is typically used in the Application Server or when running Embedded to control which port is used for outbound connections. If the default is used, which is 0, then the connector will let the system pick up an ephemeral port. Valid ports are 0 to 65535

nioRemotingThreads

Both

When configured to use NIO, the broker will by default use a number of threads equal to three times the number of cores (or hyper-threads) as reported by Runtime.getRuntime().availableProcessors() for processing incoming packets. If you want to override this value, you can set the number of threads by specifying this parameter. The default value for this parameter is -1, which means use the value derived from Runtime.getRuntime().availableProcessors() * 3.

tcpNoDelay

Both

If this is true then Nagle’s algorithm will be disabled. This is a Java (client) socket option. The default value is true.

tcpReceiveBufferSize

Both

Determines the size of the TCP receive buffer in bytes. The default value is 32768.

tcpSendBufferSize

Both

Determines the size of the TCP send buffer in bytes. The default value is 32768.

TCP buffer sizes should be tuned according to the bandwidth and latency of your network.

In summary TCP send/receive buffer sizes should be calculated as:

buffer_size = bandwidth * RTT.

Where bandwidth is in bytes per second and network round trip time (RTT) is in seconds. RTT can be easily measured using the ping utility.

For fast networks you may want to increase the buffer sizes from the defaults.

Table A.2. Netty HTTP Parameters

ParameterUse with…​Description

httpClientIdleTime

Acceptors

How long a client can be idle before sending an empty HTTP request to keep the connection alive.

httpClientIdleScanPeriod

Acceptors

How often, in milliseconds, to scan for idle clients.

httpEnabled

Acceptors

No longer required. With single port support the broker will now automatically detect if HTTP is being used and configure itself.

httpRequiresSessionId

Both

If true the client will wait after the first call to receive a session id. Used when an HTTP connector is connecting to a servlet acceptor. This configuration is not recommended.

httpResponseTime

Acceptors

How long the server can wait before sending an empty HTTP response to keep the connection alive.

httpServerScanPeriod

Acceptors

How often, in milliseconds, to scan for clients needing responses.

Table A.3. Netty TLS/SSL Parameters

ParameterUse with…​Description

enabledCipherSuites

Both

Comma separated list of cipher suites used for SSL communication. The default value is empty which means the JVM’s default will be used.

enabledProtocols

Both

Comma separated list of protocols used for SSL communication. The default value is empty which means the JVM’s default will be used.

keyStorePassword

Both

When used on an acceptor this is the password for the server-side keystore.

When used on a connector this is the password for the client-side keystore. This is only relevant for a connector if you are using 2-way SSL (that is, mutual authentication). Although this value can be configured on the server, it is downloaded and used by the client. If the client needs to use a different password from that set on the server then it can override the server-side setting by either using the customary javax.net.ssl.keyStorePassword system property or the ActiveMQ-specific org.apache.activemq.ssl.keyStorePassword system property. The ActiveMQ-specific system property is useful if another component on client is already making use of the standard, Java system property.

keyStorePath

Both

When used on an acceptor this is the path to the SSL key store on the server which holds the server’s certificates (whether self-signed or signed by an authority).

When used on a connector this is the path to the client-side SSL key store which holds the client certificates. This is only relevant for a connector if you are using 2-way SSL (that is, mutual authentication). Although this value is configured on the server, it is downloaded and used by the client. If the client needs to use a different path from that set on the server then it can override the server-side setting by either using the customary javax.net.ssl.keyStore system property or the ActiveMQ-specific org.apache.activemq.ssl.keyStore system property. The ActiveMQ-specific system property is useful if another component on client is already making use of the standard, Java system property.

needClientAuth

Acceptors

Tells a client connecting to this acceptor that 2-way SSL is required. Valid values are true or false. Default is false.

sslEnabled

Both

Must be true to enable SSL. Default is false.

trustStorePassword

Both

When used on an acceptor this is the password for the server-side trust store. This is only relevant for an acceptor if you are using 2-way SSL (that is, mutual authentication).

When used on a connector this is the password for the client-side truststore. Although this value can be configured on the server, it is downloaded and used by the client. If the client needs to use a different password from that set on the server then it can override the server-side setting by either using the customary javax.net.ssl.trustStorePassword system property or the ActiveMQ-specific org.apache.activemq.ssl.trustStorePassword system property. The ActiveMQ-specific system property is useful if another component on client is already making use of the standard, Java system property.

trustStorePath

Both

When used on an acceptor this is the path to the server-side SSL key store that holds the keys of all the clients that the server trusts. This is only relevant for an acceptor if you are using 2-way SSL (that is, mutual authentication).

When used on a connector this is the path to the client-side SSL key store which holds the public keys of all the servers that the client trusts. Although this value can be configured on the server, it is downloaded and used by the client. If the client needs to use a different path from that set on the server then it can override the server-side setting by either using the customary javax.net.ssl.trustStore system property or the ActiveMQ-specific org.apache.activemq.ssl.trustStore system property. The ActiveMQ-specific system property is useful if another component on client is already making use of the standard, Java system property.

verifyHost

Both

When used on an acceptor the CN of the connecting client’s SSL certificate will be compared to its hostname to verify they match. This is useful only for 2-way SSL.

When used on a connector the CN of the server’s SSL certificate will be compared to its hostname to verify they match. This is useful for both 1-way and 2-way SSL.

Valid values are true or false. Default is false.