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 |
| 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 |
|
DEPRECATED SINCE 6.11. Use Remote Servers in preference.
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 |
|---|
| 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 |
| 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 |
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 |
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
DEPRECATED SINCE 6.11. Use Remote Servers in preference.
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
DEPRECATED SINCE 6.11. Use Remote Servers in preference.
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 |
fanout-link
DEPRECATED SINCE 6.11. Use Remote Servers in preference.
Represents a selection of topics from the primary topic tree to be
replicated to the secondary server.
The following table lists the attributes that an element of type
fanout-link can have:
| Name |
Type |
Description |
Required |
|---|
| name |
push:string |
The fanout link name. If a value is not specified the link
name will be the same as the selector value.
In a future release this attribute will be mandatory.
|
false |
The following table lists the elements that an element of type
fanout-link can contain:
| Name |
Type |
Description |
Min
occurs |
Max occurs |
|---|
| selector |
push:string |
A topic selector specifying the topics to be replicated.
This must not overlap (select the same topics as) any other link within this
or any other connection configured for the secondary server.
|
1 |
1 |
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 |