Appendix A. Acceptor and Connector Configuration Parameters
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 Configuring acceptors and connectors in network connections 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 . Table A.1. Netty TCP Parameters Parameter Use 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 allows. 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. The default value is -1 , which means that there is no limit to the number of connections that the acceptor allows. 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 Parameter Use 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 Parameter Use 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. forceSSLParameters Connectors Controls whether any SSL settings that are set as parameters on the connector are used instead of JVM system properties (including both javax.net.ssl and AMQ Broker system properties) to configure the SSL context for this connector. Valid values are true or false . The default value is false . 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 two-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 two-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 two-way SSL is required. Valid values are true or false . The default value is false . sslEnabled Both Must be true to enable SSL. The default value is false . trustManagerFactoryPlugin Both Defines the name of the class that implements org.apache.activemq.artemis.api.core.TrustManagerFactoryPlugin . This is a simple interface with a single method that returns a javax.net.ssl.TrustManagerFactory . The TrustManagerFactory is used when the underlying javax.net.ssl.SSLContext is initialized. This allows fine-grained customization of who or what the broker and client trust. The value of trustManagerFactoryPlugin takes precedence over all other SSL parameters that apply to the trust manager (that is, trustAll , truststoreProvider , truststorePath , truststorePassword , and crlPath ). You need to place any specified plugin on the Java classpath of the broker. You can use the <broker_instance_dir> /lib directory, since it is part of the classpath by default. 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 two-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. sniHost Both When used on an acceptor, sniHost is a regular expression used to match the server_name extension on incoming SSL connections (for more information about this extension, see https://tools.ietf.org/html/rfc6066 ). If the name doesn't match, then the connection to the acceptor is rejected. A WARN message is logged if this happens. If the incoming connection doesn't include the server_name extension, then the connection is accepted. When used on a connector, the sniHost value is used for the server_name extension on the SSL connection. sslProvider Both Used to change the SSL provider between JDK and OPENSSL . The default is JDK . If set to OPENSSL , you can add netty-tcnative to your classpath to use the natively-installed OpenSSL. This option can be useful if you want to use special ciphersuite-elliptic curve combinations that are supported through OpenSSL but not through the JDK provider. 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 two-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. useDefaultSslContext Connector Allows the connector to use the "default" SSL context (via SSLContext.getDefault() ), which can be set programmatically by the client (via SSLContext.setDefault(SSLContext) ). If this parameter is set to true , all other SSL-related parameters except for sslEnabled are ignored. Valid values are true or false . The default value is false . verifyHost Both When used on a connector, the CN or Subject Alternative Name values of the server's SSL certificate are compared to the hostname being connected to in order to verify that they match. This is useful for both one-way and two-way SSL. When used on an acceptor, the CN or Subject Alternative Name values of the connecting client's SSL certificate are compared to its hostname to verify that they match. This is useful only for two-way SSL. Valid values are true or false . The default value is true for connectors and false for acceptors. wantClientAuth Acceptors Tells a client connecting to this acceptor that two-way SSL is requested, but not required. Valid values are true or false . The default value is false . If the property needClientAuth is set to true , then that property takes precedence and wantClientAuth is ignored.