Connectors.xml
This file specifies the schema for the connectors properties.
connectors
Connectors
The following table lists the elements that an element of type connectors can contain:
| Name | Type | Description | Min occurs | Max occurs |
|---|---|---|---|---|
| connector | Connector definition | 0 | unbounded |
compression-schemes
The following table lists the elements that an element of type compression-schemes can contain:
| Name | Type | Description | Min occurs | Max occurs |
|---|---|---|---|---|
| compression-scheme | 0 | unbounded |
connector
Connector definition
The following table lists the attributes that an element of type connector can have:
| Name | Type | Description | Required |
|---|---|---|---|
| name | push:string | The connector name | true |
The following table lists the elements that an element of type connector can contain:
| Name | Type | Description | Min occurs | Max occurs |
|---|---|---|---|---|
| required | push:boolean | This setting specifies if the connector must start successfully when the server is started. If the connector is required (set to true) and the server can not start it during start-up (after waiting for any start conditions} that are configured), the server is stopped. By default, this is set to true. | 0 | 1 |
| host | push:string | The name or the IP address that the connector binds to. This is optional. | 0 | 1 |
| port | push:port | The port on which the connector accepts connections. | 1 | 1 |
| backlog | push:positiveNonZeroInt | The requested maximum queue length for incoming connection requests. It is rarely necessary to tune this value. Operating System settings must be adjusted in tandem. On Linux, the appropriate setting is net.core.somaxconn. If a value is not specified, a default of 1000 is used. | 0 | 1 |
| socket-conditioning | Describes the properties associated with TCP socket connections. | 1 | 1 | |
| max-queued-bytes | push:long-bytes | The maximum number of bytes that can be queued for all sessions connected through this connector. If the number of bytes queued for a connector exceeds this number, the server may disconnect clients. If not set then no limit is applied. | 0 | 1 |
| web-server | push:string | If this connector is required to serve HTTP requests, this element specifies a web-server entry in WebServer.xml. If a value is not specified, the connector cannot serve HTTP requests. This is also required in order to be able to service websocket connections. | 0 | 1 |
| validation-policy-file | push:string | The location/name of a connection validation policy file to use for this connector. Applies only to type 'all' or 'client'. | 0 | 1 |
| key-store | Keystore details for any connector that is to support secure (TLS) connections. If this is not specified, TLS connections are not supported. | 0 | 1 | |
| queue-definition | push:string | An optional queue definition to use for this connector. This applies only to connectors of type 'all' or 'client'. The definition must exist in Server.xml. If this is not specified, the default queue definition specified in Server.xml is used. | 0 | 1 |
| reconnect | Optional reconnection properties which apply only to connectors that accept 'client' connections. If this is not specified, reconnection of client connections is not supported. | 0 | 1 | |
| ignore-errors-from | Specifies addresses from which connection errors can be ignored. This is useful for masking errors that might be reported due to the connector port being pinged by some known external entity. | 0 | 1 | |
| thread-pool-definition | push:string | Optionally, this can be used to specify a thread pool definition to be used for this connector to create its own inbound thread pool. If specified, the thread pool definition must exist in Server.xml. If a value is not specified, the default inbound thread pool is used. | 0 | 1 |
| selector-thread-pool-definition | push:string | Optionally, this can be used to specify a selector thread pool definition to be used for this connector to deal with NIO operations. If specified, the selector thread pool definition must exist in Server.xml. If a value is not specified, the default selector thread pool is used. | 0 | 1 |
| system-ping-frequency | push:millis | This indicates the interval at which clients are pinged by the server to ensure that they are still connected. If a response is not received from the client before the expiry of another interval period, the client is assumed to be disconnected. If this is not specified or a value of 0 is supplied, clients are not automatically pinged. | 0 | 1 |
| proxy-protocol | Indicates the proxy protocol required for connection. Can have the values 'NONE' or 'HA_PROXY'. The default value is 'NONE'. Only connections with the protocol specified are allowed. On publicly accessible connectors, ensure that this value is set to NONE. 'HA_PROXY' refers to the proxy protocol that was first implemented by HAProxy but it is also supported by others including Amazon's Elastic Load Balancer. | 0 | 1 | |
| connection-timeout | push:millis | This is the time in milliseconds allowed for a connection to take place and complete its handshake processing. If this value is not specified for a connector, the value set in Server.xml is used. | 0 | 1 |
| compression-schemes | The compression schemes supported by this connector. The server will use this setting to select an appropriate compression scheme for each session using this connector based on the capabilities declared by the client. The Java, Android, .NET and JavaScript client libraries all support the zlib compression scheme. A JavaScript client must explicitly download the zlib library; it is packaged separately to reduce the download size of the core library. If the compression-schemes element is missing, all compression schemes are supported by this connector. If the compression-schemes element has no compression-scheme child elements, no compression schemes are supported by this connector. That is, compression is disabled. | 0 | 1 | |
| start-conditions | Optional set of conditions that must be satisfied before the connector is automatically started. | 0 | 1 | |
| protocols | Optional list of client protocols supported by this connector. If this element is absent, all protocols are supported. If this element is present but empty, no protocols are supported. | 0 | 1 |
socket-conditioning
Describes properties associated with TCP socket connections.
The following table lists the elements that an element of type socket-conditioning can contain:
| Name | Type | Description | Min occurs | Max occurs |
|---|---|---|---|---|
| input-buffer-size | push:bytes | Specifies the size of the socket input buffer to use for each connection. If a value is not specified, a default of 128k is used. The greater of this value and the max-message-size set in Server.xml is used when setting the socket input buffer size. | 0 | 1 |
| output-buffer-size | push:bytes | This value specifies the size of the output buffer to use for each connection. This must be large enough to accommodate the largest message to be sent. Messages are 'batched' into this buffer and so the larger the buffer, the more messages can be sent in a single write. If a value is not specified, a default of 128k is used. | 0 | 1 |
| keep-alive | push:boolean | This enables or disables TCP keep-alive. If a value is not specified, a default of true is used. | 0 | 1 |
| no-delay | push:boolean | This enables or disables TCP_NODELAY (disable/enable Nagle's algorithm). If a value is not specified, a default of true is used. | 0 | 1 |
| reuse-address | push:boolean | When a TCP connection is closed the connection can remain in a timeout state for a period of time after the connection is closed (typically known as the TIME_WAIT state or 2MSL wait state). For applications using a well-known socket address or port, it might not be possible to bind a socket to the required SocketAddress if there is a connection in the timeout state involving the socket address or port. Enabling this feature allows the socket to be bound even though a previous connection is in a timeout state. If this value is not specified, the feature is enabled. | 0 | 1 |
reconnect
Reconnect properties.
The following table lists the elements that an element of type reconnect can contain:
| Name | Type | Description | Min occurs | Max occurs |
|---|---|---|---|---|
| keep-alive | push:millis | This specifies the reconnection timeout. During this period a disconnected client can reconnect to the same client session. Messages for the client continue to be queued during this period. The default is 5 minutes, meaning reconnection is enabled. Set this value to 0 to disable reconnection. | 0 | 1 |
| max-depth | push:positiveInt | As messages continue to be queued for a client whilst it is disconnected, this enables you to specify a larger maximum queue size that is used during the period that the client is disconnected. When the client reconnects, the maximum reverts back to its previous size (once any backlog had been cleared). If the specified size is not greater than the current maximum size, this has no effect. If this value is not specified, a default of 0 is used which means that no attempt is made to extend the queue size when a client is disconnected. | 0 | 1 |
| recovery-buffer-size | push:positiveInt | If the keep-alive time is not zero, this connector supports reconnection. For each client connected via this connector, the server will retain a buffer of up to recovery-buffer-size sent messages. If a client disconnects and reconnects, the server uses the buffer to re-send messages that the client has not received. The default value is 128 messages. Higher values increase the chance of successful reconnection, but increase the per-client memory footprint. | 0 | 1 |
key-store-definition
The keystore definition that allows TLS connection to a connector.
The following table lists the attributes that an element of type key-store-definition can have:
| Name | Type | Description | Required |
|---|---|---|---|
| mandatory | push:boolean | If this is set to true, all connections must use this keystore and TLS connection is mandatory. If a value is not specified, a default of false is used, meaning that the connector accepts either TLS or non-TLS connections. | false |
The following table lists the elements that an element of type key-store-definition can contain:
| Name | Type | Description | Min occurs | Max occurs |
|---|---|---|---|---|
| file | push:string | The keystore file path. | 1 | 1 |
| password | push:string | The password for the keystore. | 1 | 1 |
ignore-errors-from
Some external monitors cause the Diffusion server to log errors, as it is not a valid Diffusion connection. Adding the remote IP address to this list ensure that the errors are not logged.
The following table lists the elements that an element of type ignore-errors-from can contain:
| Name | Type | Description | Min occurs | Max occurs |
|---|---|---|---|---|
| ip-address | push:string | An IP address or unknown if the remote IP address is being masked. | 1 | unbounded |
start-condition-list
The following table lists the elements that an element of type start-condition-list can contain:
| Name | Type | Description | Min occurs | Max occurs |
|---|---|---|---|---|
| fanout-ready | A fanout ready condition is satisfied when a fanout link with the given connection and link names exists, has connected to the primary server, and has synchronized all of the topics on the primary server that match its configuration. | 0 | unbounded | |
| connection | push:string | 0 | unbounded | |
| link | push:string | 0 | unbounded | |
| remote-topic-view-ready | A remote topic view ready condition is satisfied when a remote topic view with the given name exists, has connected to the remote server, and has evaluated all of the topics on the remote server that match its configuration. | 0 | unbounded | |
| name | push:string | 0 | unbounded | |
| cluster-configuration-restored | A cluster configuration restored condition is satisfied when the server is configured as part of a cluster, has joined the cluster, and has completed restoration of shared configuration. | 0 | 1 | |
| replicated-topics-restored | A replicated topics restored condition is satisfied when the server is configured as part of a cluster, has joined the cluster, and has completed restoration of replicated topics. | 0 | 1 | |
| persisted-topics-restored | A persisted topics restored condition is satisfied when the server has restored its persisted topics. | 0 | 1 |
protocols
The following table lists the elements that an element of type protocols can contain:
| Name | Type | Description | Min occurs | Max occurs |
|---|---|---|---|---|
| protocol | 0 | unbounded |
connectorType
This value must be a push:string.
The following values are allowed:
- all
- client
- policy
proxyProtocol
This value must be a push:string.
The following values are allowed:
- NONE
- HA_PROXY
compression-scheme
This value must be a push:string.
The following values are allowed:
- ZLIB
protocol
This value must be a push:string.
The following values are allowed:
- DIFFUSION_WEBSOCKET
- DIFFUSION_HTTP_LONG_POLL
- MQTT_TCP
- MQTT_WEBSOCKET