Just a second...

Server.xml

This file specifies the schema for the server properties, as well as multiplexers, security, conflation, client queues, and thread pools.

server

All server properties

The following table lists the elements that an element of type server can contain:
Name Type Description Min occurs Max occurs
server-name push:string The server name is used to identify this server if running in a cluster. If not specified, the local hostname is used. 0 1
persistence-directory push:string The path of a directory that is to be used to hold persistent files. This may be an absolute path or a relative path. A relative path will be taken to be relative to the Diffusion home directory. If this is not specified then the value of the persistence store-directory will be considered and if no directory is specified there then a relative path of 'persistence' will be used. The directory will be created if it does not already exist. 0 1
max-message-size push:bytes The maximum message size in bytes. This defines the maximum message size (including headers) that can be received. 1 1
multiplexer   Properties that define the multiplexers. 0 1
security   Properties relating to security (optional). 0 1
client-queues   Definitions of client queues. 1 1
connection-timeouts   Timeout values relating to connections. If a value is not specified, defaults are used. 0 1
thread-pools   Definitions of thread pools 1 1
selector-thread-pools   Definitions of thread pools 0 1
auto-deployment   Automatic deployment properties (optional). If not specified then auto deployment is not enabled. 0 1
geo-ip   Properties relating to the Geo IP lookup facility. If a value is not specified, defaults are used. 0 1
usr-lib   User libraries (optional). 0 1
hooks   User hooks used in the server (optional) 0 1
fanout   Properties relating to fan-out (optional). If not specified then the server will not be enabled as a fan-out secondary server. 0 1
persistence   Properties relating to topic tree persistence (optional). If not specified, persistence will not be enabled. 0 1
default-log-directory push:string The default log directory path. The directory is used for the daily ConnectionCount statistics file and multiplexer diagnostic files, and is used to resolve the value configured using the console-monitored log element. If not set, the default path is "logs". If the path is relative, it is evaluated relative to the Diffusion installation directory. 0 1
console-monitored-log push:string The log file made available to the Diffusion management console. This should be configured to match etc/log4j2.xml. If not set, the default path is 'Server.log'. If the path is relative, it is evaluated relative to the default log directory. 0 1

multiplexer

Multiplexer configuration. Multiplexers are responsible for subscription evaluation and output processing. Each session hosted by the server is allocated to a multiplexer. Each multiplexer uses a CPU core.

The following table lists the elements that an element of type multiplexer can contain:
Name Type Description Min occurs Max occurs
size push:positiveInt The number of multiplexer instances. Each multiplexer uses a CPU core. If the server will host a large number of sessions, and there are spare CPU cores available, increase this number. If a value is not specified, a default value equal to half the number of available CPU cores is used. 0 1
latency-warning push:millis The multiplexer latency warning threshold. This setting controls the threshold at which to issue a warning if the multiplexer is taking too long to complete an operational cycle. The default value is 1000 (1 second). Warnings are logged to the server log at info level. 0 1
monitor-period push:millis The multiplexer progress monitoring period. A watchdog task checks the multiplexer every period. If the multiplexer has not completed at least one operational cycle in this time, a diagnostic warning will be logged to the server log. The default value is 5000 (5 seconds). 0 1
max-event-queue-size push:positiveInt The maximum number of entries in the multiplexer event queue. The default value is 128k. Under normal circumstances this value should not be changed from the default. 0 1

hooks

User hooks used in the server.

The following table lists the elements that an element of type hooks can contain:
Name Type Description Min occurs Max occurs
startup-hook push:string This is the class name of a class that implements the interface com.pushtechnology.diffusion.api.publisher.ServerStartupHook. If specified, the hook is instantiated and the serverStarting method called when the server is starting. 0 1
shutdown-hook push:string This is the class name of a class that implements the interface com.pushtechnology.diffusion.api.publisher.ServerShutdownHook. If specified, the hook is instantiated and the serverStopping method called when the server is stopping. 0 1

security

Server security properties.

The following table lists the elements that an element of type security can contain:
Name Type Description Min occurs Max occurs
authorisation-handler-class push:string DEPRECATED: Since 6.5. This element is ignored and should be removed from your configuration. 0 1
authentication-handlers     0 1

authentication-handlers

Authentication handlers, in order of decreasing precedence. The authentication handlers are called to authenticate new connections and changes to the principal associated with a session. Authentication handlers are configured in precedence order. Authentication succeeds if a handler returns "allow" and all higher precedence handlers (earlier in the order) return "abstain". Authentication fails if a handler returns "deny" and all higher precedence handlers return "abstain". If all authentication handlers return "abstain", the request is denied. After the outcome is known, the server might choose not to call the remaining handlers.

The following table lists the elements that an element of type authentication-handlers can contain:
Name Type Description Min occurs Max occurs
authentication-handler   An authentication handler hosted by the server. 0 unbounded
control-authentication-handler   An authentication handler registered by a client. 0 unbounded
system-authentication-handler   An authentication handler that uses the configured system authentication store to validate principals and to define an action for anonymous logins. The XSD does not prevent you from configuring the system authentication multiple times. However, the Diffusion server restricts this and will not start if you define the system authentication handler more than once. 0 unbounded

server-authentication-handler

An authentication handler hosted by the server. The handler is instantiated when the server starts.

The following table lists the attributes that an element of type server-authentication-handler can have:
Name Type Description Required
class push:string The class attribute specifies the fully qualified name of a handler implementation class that implements the com.pushtechnology.diffusion.client.security.authentication.Authenticator interface. The class must be available on the classpath. true

system-authentication-handler

The system authentication handler uses the configured system authentication store to validate principals and to define an action for anonymous logins. If the system handler is specified then it will check if a principal is specified in the store and if so will validate its credentials against the store. The store may also specify additional assigned roles to be granted to a principal. If a principal is not specified in the store then the handler will abstain. The store may indicate whether to allow, deny or abstain for anonymous logins.

The following table lists the attributes that an element of type system-authentication-handler can have:
Name Type Description Required
hash-scheme push:string The hash scheme used to store newly created passwords. More complex algorithms generate password hashes that are more expensive for an attacker to crack by brute force, but require more CPU for each authentication operation. The following schemes are supported: "NONE"; "DESEDE"; "PBKDF-SHA1-N", where N is the number of iterations; "PBKDF-SHA256-N", where N is the number of iterations. The default scheme is PBKDF-SHA256-1000. The configured scheme must be supported by the JVM or the server will not start. All of the above schemes are supported by the standard Java 8 JDK. false

control-authentication-handler

Client sessions register control authenticators using an identifying name. A <control-authentication-handler> must be configured with a matching handler-name. Configure at most one <control-authentication-handler> for a handler-name.

The following table lists the attributes that an element of type control-authentication-handler can have:
Name Type Description Required
handler-name push:string The handler name attribute must match the identifying name used by the client session to register a control authenticator. true

client-queues

Client queue definitions.

The following table lists the elements that an element of type client-queues can contain:
Name Type Description Min occurs Max occurs
default-queue-definition push:string The name of the queue definition to use by default. Connectors that do not explicitly specify a queue definition use the one specified here. 1 1
queue-definition   Queue definition. 1 unbounded

queue-definition

This defines the properties of a client queue.

The following table lists the attributes that an element of type queue-definition can have:
Name Type Description Required
name push:string The queue definition name. true
The following table lists the elements that an element of type queue-definition can contain:
Name Type Description Min occurs Max occurs
max-depth push:positiveInt The maximum depth of the queue. If the number of messages queued for a client exceeds this number, the server disconnects the client. If not set then no limit is applied. When using topic replication, it is recommended that the max-depth of the queue defined for the connector used by replication is set to 2 times the expected topic tree size. When a server disconnects and then reconnects, the entire topic tree needs to be replicated. As a result 1 or 2 messages are en-queued per topic (1 if the topic has no value, 2 if it does). The element to be adjusted is the one inside the Connectors.xml under the largeQueue configuration, as this is the one used for the replicating servers' sessions. 0 1
max-bytes push:long-bytes The maximum byte depth of the queue. If the number of bytes queued for a client exceeds this number, the server disconnects the client. If not set then no limit is applied. 0 1
conflates push:boolean Specifies whether conflation is enabled by default for queues that use this queue definition. If this value is not specified, conflation is enabled. Conflation can be enabled or disabled for individual sessions at runtime. The behavior when conflation is enabled is determined by the conflation policies of topics. 0 1
upper-threshold push:percent This specifies a percentage of the maximum queue size and if this value is reached then any listeners are notified. Notification occurs only once and does not occur again until the queue has returned to the lower threshold. If this value is not specified, no upper limit notification occurs. 0 1
lower-threshold push:percent This specifies a percentage of the maximum queue size and indicates the level at which listeners are notified after an upper limit notification has occurred and the queue size has dropped back to the specified lower limit. If this value is not specified, no lower limit notification occurs. 0 1

connection-timeouts

Connection-related timeouts.

The following table lists the elements that an element of type connection-timeouts can contain:
Name Type Description Min occurs Max occurs
write-timeout push:millis The write timeout in milliseconds for blocking write operations. Most write operations are non-blocking and are not affected by this timeout. Blocking writes include connection responses to new clients, and HTTP responses to web server requests. If this value is not specified, a default of 3 seconds is used. If this exceeds one hour (3600000ms) a warning will be logged and the time-out will be set to one hour. 0 1
connection-timeout push:millis The time in milliseconds allowed for a connection to complete its handshake processing, including the time taken to call any configured authentication handlers and look up location details. If this value is not specified, a default of 5 seconds is used. If this exceeds one hour (3600000ms) a warning will be logged and the time-out will be set to one hour. 0 1

thread-pools

Thread pools.

The following table lists the elements that an element of type thread-pools can contain:
Name Type Description Min occurs Max occurs
inbound push:string Name of the inbound thread pool definition. 1 1
background-thread-size push:int Number of threads to use for the background thread pool. If a value is not specified, a default of 10 is used. 0 1
thread-pool-definition   Thread pool definition. 1 unbounded

thread-pool-definition

Thread pool definition.

The following table lists the attributes that an element of type thread-pool-definition can have:
Name Type Description Required
name push:string Name of the thread pool definition. true
The following table lists the elements that an element of type thread-pool-definition can contain:
Name Type Description Min occurs Max occurs
size push:positiveInt The size of the thread pool. 0 1
core-size push:positiveInt DEPRECATED: since 6.5. Use size instead, which takes precedence over this setting. 0 1
max-size push:positiveInt DEPRECATED: since 6.5. This setting is ignored and should be removed from your configuration. 0 1
queue-size push:positiveInt The thread pool queue size. When the max-size is reached, tasks are queued. If the value is 0, the queue is unbounded. If the value is not 0, it must be at least 10. 1 1
keep-alive push:millis DEPRECATED: since 6.5. This setting is ignored and should be removed from your configuration. 0 1
rejection-handler-class push:string DEPRECATED: since 6.5. This setting is ignored and should be removed from your configuration. 0 1

selector-thread-pools

Selector Thread pools. By default a single pool called "SelectorThreadPool" of size 1 is set up

The following table lists the elements that an element of type selector-thread-pools can contain:
Name Type Description Min occurs Max occurs
default push:string Name of the default selector thread pool definition. If not specified then "SelectorThreadPool" is assumed. 0 1
selector-thread-pool-definition   Selector thread pool definition. 1 unbounded

selector-thread-pool-definition

Selector thread pool definition.

The following table lists the attributes that an element of type selector-thread-pool-definition can have:
Name Type Description Required
name push:string Name of the selector thread pool definition. true
The following table lists the elements that an element of type selector-thread-pool-definition can contain:
Name Type Description Min occurs Max occurs
size push:positiveInt The number of selector threads to have running in the thread pool. The number of selector threads created is the maximum of the value defined here and the number of acceptors defined in the Connectors.xml file. This number is fixed and does not change at runtime. 0 1

auto-deployment

Auto deployment details. DEPRECATED: Since 6.5. This element is ignored and should be removed from your configuration.

The following table lists the elements that an element of type auto-deployment can contain:
Name Type Description Min occurs Max occurs
directory push:string The name of the automatic deployment directory relative to the Diffusion home directory. 1 1
scan-frequency push:millis The frequency at which the deployment directory is scanned for new deployments. If a value is not specified, a default of 5 seconds is used. 0 1

geo-ip

GeoIP details.

The following table lists the attributes that an element of type geo-ip can have:
Name Type Description Required
enabled push:boolean Set to true to enable GeoIP lookup. This needs to be set to true if you are going to use connection or subscription validation policies. If a value is not specified, a default of true is used. false
The following table lists the elements that an element of type geo-ip can contain:
Name Type Description Min occurs Max occurs
file-name push:string The name of the Maxmind GeoCityIP city file. If a value is not specified, the default of "data/GeoLite2-City.mmdb" is used. 0 1

usr-lib

A list of user libraries from which user code is loaded.

The following table lists the elements that an element of type usr-lib can contain:
Name Type Description Min occurs Max occurs
directory push:string Directory to load classes from. When the server starts, this folder is traversed, including subdirectories and all jars or zip files added to the class loader. 1 unbounded

fanout

Specifies fan-out connections to establish with primary servers. Typically there is a single connection but it is possible to replicate topics from more than one primary server as long as they do not overlap. All such connections are automatically established when the secondary server starts and will recover as configured.

The following table lists the elements that an element of type fanout can contain:
Name Type Description Min occurs Max occurs
connection   A fan out connection. 0 unbounded

fanout-connection

Represents a fan-out connection from a secondary server to a primary server.

The following table lists the attributes that an element of type fanout-connection can have:
Name Type Description Required
name push:string The fanout connection name. If a value is not specified the connection name will be the same as the url value. In a future release this attribute will be mandatory. false
The following table lists the elements that an element of type fanout-connection can contain:
Name Type Description Min occurs Max occurs
url push:string The connection URL which specifies the primary server to connect to. 1 1
principal push:string The principal used to connect to the primary server. If not specified, an anonymous connection is assumed. 0 1
password push:string The password to use for the connection. If not specified, no credentials are assumed. 0 1
retry-delay push:millis This is the time to wait after failing to connect or losing a connection before trying to connect again. The value is specified in milliseconds. If this value is not specified, a default of 1s is used. 0 1
reconnect-timeout push:millis This is the total time in milliseconds that will be allowed to reconnect a failed connection to the primary server. For reconnection to work the primary server connector must have been configured to support reconnection. If this is not specified, a value of 60s is assumed. If reconnection is configured and a load balancer is in use then it must be configured for sticky routing. 0 1
recovery-buffer-size push:int If the primary server is configured to support reconnection, a session established with a non-zero reconnect-timeout retains a buffer of sent messages. If the session disconnects and reconnects, this buffer is used to re-send messages that the server has not received. The default value is 10,000 messages. If reconnect-timeout is 0 then this value is ignored. 0 1
input-buffer-size push:bytes Specifies the size of the input buffer to use for the connection with the primary server. This is used to receive messages from the primary server. Set this to the same size as the output buffer used at the primary server. If not specified, a default of 1024k is used. 0 1
output-buffer-size push:bytes The size of the output buffer to use for the connection with the primary server. This is used to send messages to the primary server. Set this to the same size as the input buffer used by the primary server. If not specified, a default of 1024k is used. 0 1
maximum-queue-size push:int The maximum number of messages that can be queued to send to the primary server. If this number is exceeded, the connection will be closed. This must be sufficient to cater for messages that may be queued whilst disconnected (awaiting reconnect). The default value is 10,000 messages. 0 1
connection-timeout push:millis This specifies the connection timeout value (in milliseconds). If a value is not specified, a default of 2s is used. 0 1
write-timeout push:millis This specifies the write timeout value (in milliseconds). If a value is not specified, a default of 2s is used. 0 1
link   Specifies a link to a selection of topics at the primary server that are to be replicated at the secondary server. 1 unbounded

persistence

Specifies requirements for topic tree persistence. If persistence is enabled, all topics and all updates to those topics will be persisted to append-only log files. Upon restart of the server, persisted topics are restored to their latest persistent state.

The following table lists the attributes that an element of type persistence can have:
Name Type Description Required
enabled push:boolean Indicates whether the persistence service is enabled. The default is 'true' if the persistence element is present but this attribute is not specified. false