Configuration

This guide describes the configuration of MigratoryData Server. It is recommended to read the Architecture Guide before reading this document for a better understanding of the concepts and to have a more comprehensive background.

Using Configuration File

The configuration file of the MigratoryData server has comments and optional parameters besides required parameters. The optional parameters have default values. An optional parameter that is not present in the configuration file will be used with its default value.

The configuration file supports comments. A line which starts with a # character is interpreted as a comment and is ignored. A parameter can be configured with the following syntax:

parameter = value

The value of a parameter can be defined on multiple lines by postfixing each line with \. For example

LicenseKey = aaaabbbbcccc

can be written as follows:

LicenseKey = aaaa\
             bbbb\
             cccc

The configurable parameters are described in the sections 4 and 5 below.

Using Environment Variables

Use this environment variable to define various extra options for MigratoryData Server.

You might use one or more of the environment variables defined below to customize various aspects of your MigratoryData deployment. These environment variables should be defined in the following system configuration file:

System configuration file

Platform

/etc/default/migratorydata

For deb-based Linux (Debian, Ubuntu)

/etc/sysconfig/migratorydata

For rpm-based Linux (RHEL, CentOS)

MIGRATORYDATA_EXTRA_OPTS

Description

Specifies various extra options for MigratoryData Server

Default value

""

Required parameter

Optional

Use this environment variable to define various extra options for MigratoryData Server. Thus it can be used to configure default parameters which are not yet set in the configuration file, or override parameters which are already configured.

Every configurable parameter of the MigratoryData server can be either configured in the configuration file, or specified as an extra option with the MIGRATORYDATA_EXTRA_OPTS environment variable using the following syntax:

-Dparameter=value

The value of a parameter should be defined without spaces and quotes. For example, use -DMemory=512MB, rather than -DMemory='512 MB'. Likewise, use -DLogFolder=/tmp/somefile, rather than -DLogFolder="/tmp/some file".

Also, the value cannot be defined on multiple lines. For example, if the LicenseKey parameter is configured in your configuration file on multiple lines as follows:

LicenseKey = aaaa\
             bbbb\
             cccc

then, you could redefine it as an extra option only as follows -DLicenseKey=aaaabbbbcccc.

Important

A parameter defined using an extra option will override the value of that parameter defined in the configuration file. This is typically the goal of the extra options. For example, an extra option could be used to temporarily test a feature of your deployment without modifying the configuration file.

Another use of extra options is when running the MigratoryData server into a container. In this case, the default configuration file cannot be typically edited inside the container, so customization is done using extra options from outside of container.

For example, to configure the JMX monitoring on the port 3000, without using authentication, or to alter the existing configuration of JMX monitoring use:

MIGRATORYDATA_EXTRA_OPTS='-DMonitor=JMX \
                          -DMonitorJMX.Listen=*:3000 \
                          -DMonitorJMX.Authentication=false'

MIGRATORYDATA_JAVA_EXTRA_OPTS

Description

Specifies various extra options for Java

Default value

""

Required parameter

Optional

Use this environment variable to define extra options for Java Virtual Machine.

For most cases, you don’t need to configure this environment variable. However, there are situations when adding an extra option for Java could be necessary.

For example, if you run the MigratoryData server into a docker container or on an AWS EC2 machine, then, in order to be able to access the JMX monitoring using the jconsole tool, you will need to provide some extra options for Java as follows:

MIGRATORYDATA_JAVA_EXTRA_OPTS='-Djava.net.preferIPv4Stack=true \
                               -Djava.rmi.server.hostname=yourhostname'

where yourhostname is the DNS name of the machine hosting the docker container, or the public DNS name of the AWS EC2 machine.

MIGRATORYDATA_JAVA_GC_OPTS

Description

Specifies various options for Java Garbage Collection

Default value

"-verbosegc -XX:+UseParallelOldGC"

Required parameter

Optional

Use this environment variable to define the Java options related to Garbage Collection. These options should not include the Java options for Garbage Collection logging which should be provided using the environment variable MIGRATORYDATA_JAVA_GC_LOG_OPTS.

For most cases, it is sufficient to use the default value of this environment variable.

MIGRATORYDATA_JAVA_GC_LOG_OPTS

Description

Specifies options for Java Garbage Collection logs

Default value for Java 8

"-XX:+PrintGCDetails \
-XX:+PrintGCTimeStamps \
-XX:+PrintGCDateStamps \
-XX:+UseGCLogFileRotation \
-XX:GCLogFileSize=10M \
-XX:NumberOfGCLogFiles=5 \
-Xloggc:YourLogFolder/all/gc-%t.log"

Default value for Java 9+

"-Xlog:gc*:file=YourLogFolder/all/gc-%t.log:time, \
uptimemillis:filecount=5,filesize=10000"

Required parameter

Optional

Use this environment variable to define the Java options related to Garbage Collection logging.

For most cases, it is sufficient to use the default value of this environment variable.

MIGRATORYDATA_MAX_DESCRIPTORS

Description

Specifies the maximum number of socket descriptors

Default value

1000000

Required parameter

Optional

Use this environment variable to define the maximum number of socket descriptors to be used by the maximum number of concurrent users connecting to the MigratoryData server.

For most cases, it is sufficient to use the default value of this environment variable.

Core Parameters

The core parameters of MigratoryData Server are described below.

LicenseKey

The license key consists of a sequence of numbers and letters. The license keys are issued by MigratoryData either for evaluation, development, or production usage of MigratoryData Server. To obtain a license key, please contact MigratoryData at support@migratorydata.com.

Memory

Description

Specify the maximum memory to be used by MigratoryData Server

Default value

No default value

Required parameter

Required

The memory size defined by this parameter can be expressed in bytes. Also, it can be expressed in gigabytes, megabytes, and kilobytes by using the following postfixes: GB for gigabytes, MB for megabytes, or KB for kilobytes.

For example, to allocate 512 megabytes for MigratoryData Server, configure the parameter Memory as follows:

Memory = 512 MB

In a production environment is is recommended to use at least 8 GB or more depending on the load of data on the server and how much simultaneous clients will be connected.

Tip

You could use MigratoryData Benchmark Kit for estimating the memory required for your use case.

Listen

Description

A comma separated list of addresses to listen for client connections

Default value

No default value

Required parameter

Optional

The format of each address of the list defined by this parameter is either IP Address:Port or DNS Name:Port.

For example, to listen for clients on the port 80 of the address 192.168.1.1, use 192.168.1.1:80. Likewise, to listen for clients on the port 8800 of the address push.example.com, use push.example.com:8800. IPv6 addresses must be enclosed in square brackets as follows [2001:db8::a00:20ff:fea7:ccea]:80.

If you specify an address without a port, the default port 80 will be used.

By specifying an IP address, MigratoryData Server will bind only to that IP address. The wildcard address (*) will enable MigratoryData Server to bind to all available IP addresses of the machine.

Caution

If MigratoryData Server is installed on a machine that has a firewall enabled, then you will need to allow in the firewall rules the access to the addresses and ports configured by this parameter.

ListenEncrypted

Description

A list of addresses to listen for encrypted client connections

Default value

No default value

Required parameter

Optional

The same conventions applies as for the Listen parameter, except the fact that if you specify an address without a port, the default port 443 will be used.

Important

In a production deployment, it is recommend to use encrypted client connections. In addition to the fact that data will be securely delivered to clients, there is another advantage. Some security solutions consider HTTP streaming as a non-standard HTTP access and may block streaming to the client having installed such a security solution. By deploying MigratoryData Server with encrypted client connections, the security solutions cannot inspect the content of the HTTP messages so that streaming cannot be blocked.

KeyStore

Description

A Java KeyStore (JKS) file with security certificates

Default value

No default value

Required parameter

Required if at least one of the following is true:

  • ListenEncrypted is configured

  • MonitorJMX.Encryption is configured on true

  • MonitorHTTP.Encryption is configured on true

The keystore file must be configured using absolute paths. For example:

KeyStore = /some/path/mykeystore.jks

For Linux/Unix

KeyStore = C:/some/path/mykeystore.jks

For Windows

The keystore must contain a SSL certificate for each address used in the configuration of the following parameters:

ListenEncrypted

MonitorJMX.Listen

provided that MonitorJMX.Encryption is set on true

MonitorHTTP.Listen

provided that MonitorHTTP.Encryption is set on true

How to add a certificate to the keystore

Suppose the following DNS address push.example.com resolves to the IP address 192.168.1.1, and vice-versa, the IP address 192.168.1.1 resolves to the DNS address push.example.com.

If an address appears in the configuration of any of the parameters used to define encrypted connections (see table parameters-encryption), then the keystore file must contain an SSL certificate for that address. If the address is specified by its DNS name, say push.example.com, then its certificate entry in the keystore must have as alias the string push.example.com. If the address is specified by its IP address, say 192.168.1.1, then its certificate entry in the keystore must have as alias the string 192.168.1.1.

To create a certificate for an address in the keystore, there are two possibilities: either use a self-signed certificate for that address or use a certificate signed by a Certificate Authority (CA).

Important

Self-signed certificates can be used for development. In a production environment always use certificates signed by a Certificate Authority.

In the next two subsections we assume that the keystore file is named mykeystore.jks and the address for which a certificate should be added in the keystore is specified either by DNS name as push.example.com or by IP address as 192.168.1.1.

Adding a self-signed certificate to the keystore

Run one of following depending on how the address was specified in the configuration file:

Certificate for DNS name

keytool -genkeypair -dname "CN=push.example.com" \
-alias push.example.com \
-keyalg RSA \
-validity 3600 \
-keystore mykeystore.jks

Certificate for IP address

keytool -genkeypair -dname "CN=192.168.1.1" \
-alias 192.168.1.1 \
-keyalg RSA \
-validity 3600 \
-keystore mykeystore.jks

Certificate for JMX monitoring

keytool -genkeypair -dname "CN=jmx" \
-alias jmx \
-keyalg RSA \
-validity 3600
-keystore mykeystore.jks

You will be asked to set a password for the keystore if the file mykeystore.jks does not exist, or to enter the keystore password if the keystore file already exists and contains other certificate entries. This password must be used to configure the parameter KeyStorePassword.

Adding a CA-signed certificate to the keystore

Suppose you obtained the following signed certificate file push.example.com.crt from a Certificate Authority for the domain push.example.com and suppose push.example.com.key is the file containing its corresponding private key.

In order to add this CA-signed certificate to the keystore, follow these steps:

  1. If the Certificate Authority provided you an intermediate certificate in addition to the signed certificate push.example.com.crt, then you will have to chain your signed certificate with the intermediary certificate. If you have not received an intermediary certificate, then just skip this step.

    To chain your signed certificate push.example.com.crt with the intermediary certificate, you should first append to your signed certificate the intermediary certificate, say intermediary.crt. Then append the certificate signing request that you sent to the CA authority, say push.example.com.csr. On Linux, use the command:

    cat intermediary.crt push.example.com.csr >> push.example.com.crt
    

    On Windows, use the command:

    type intermediary.crt push.example.com.csr >> push.example.com.crt
    
  2. Convert the CA-signed certificate to the pkcs#12 as follows:

    openssl pkcs12 -export \
    -in push.example.com.crt \
    -inkey push.example.com.key \
    -out push.example.com.pkcs12
    

    This will produce the file push.example.com.pkcs12. The password for the this new file must be the same like that used for the keystore.

  3. Add the pkcs#12 certificate obtained in the previous step to the keystore as follows:

    keytool -importkeystore \
    -srckeystore push.example.com.pkcs12 \
    -srcstoretype PKCS12 \
    -deststoretype JKS \
    -destkeystore mykeystore.jks
    

    This will insert a new entry to the keystore file mykeystore.jks with the default alias 1.

  4. Rename the default certificate alias 1 of the keystore by entering one of following commands depending on how you specified the address in the configuration file:

    Certificate for DNS name

    keytool -v -keystore mykeystore.jks \
    -changealias -alias 1 \
    -destalias push.example.com
    

    Certificate for IP address

    keytool -v -keystore mykeystore.jks \
    -changealias -alias 1 \
    -destalias 192.168.1.1
    

    Certificate for JMX monitoring

    keytool -v -keystore mykeystore.jks \
    -changealias -alias 1 \
    -destalias jmx
    

KeyStorePassword

Description

The password to access the keystore

Default value

No default value

Required parameter

Required if the parameter KeyStore is configured

Configure this parameter with the password defined when you created the keystore file. The keystore file is created when adding the first certificate entry to it as explained in the description of the KeyStore parameter.

Monitor

Description

A list of monitoring options

Default value

No default value

Required parameter

Optional

The currently available monitoring options are JMX and HTTP. You can configure JMX monitoring, HTTP monitoring, or both. Use comma separated values to configure both monitoring options as follows:

Monitor = JMX, HTTP

MonitorUsername

Description

Monitoring user name

Default value

admin

Required parameter

Required if at least one of the following is true:

  • MonitorJMX.Authentication is configured on true

  • MonitorHTTP.Authentication is configured on true

MonitorPassword

Description

Monitoring password

Default value

pass

Required parameter

Required if at least one of the following is true:

  • MonitorJMX.Authentication is configured on true

  • MonitorHTTP.Authentication is configured on true

MonitorJMX.Listen

Description

Address to listen for JMX monitoring clients

Default value

No default value

Required parameter

Optional

The format of the address used by this parameter is the same like the format of the Listen parameter.

Caution

In order to access the JMX monitoring from a remote machine, please check your firewall settings so that the network traffic from the remote machine is allowed to the address configured by this parameter.

The jconsole utility that is freely available with OpenJDK can be used for JMX monitoring. Also, there are many commercial tools for JMX that provide enhanced functionality like dashboards and database persistence that can be used.

Tip

The jconsole utility has a known issue when connecting remotely to a JMX service running on Linux. To avoid this issue, execute the following command on the Linux machine where MigratoryData Server runs:

hostname -i

The command above should return the address used in the configuration of the parameter MonitorJMX.Listen. If it reports a local address like 127.0.0.1, then jconsole would not be able to connect remotely to the JMX monitoring service of the MigratoryData server. To fix this issue, edit /etc/hosts so that hostname resolves to the address used by MonitorJMX.Listen.

To access the JMX service of the MigratoryData server running on AWS EC2, please also refer to jmx-remote-ec2.

MonitorJMX.Authentication

Description

Specify whether or not to use authentication for JMX monitoring

Default value

No default value

Required parameter

Optional

This parameter can have two values: true or false. If set on true, then, in order to access the JMX monitoring, you should use the monitoring user name specified with the MonitorUsername parameter and the monitoring password specified with the MonitorPassword parameter.

MonitorJMX.Encryption

Description

Specify whether or not to use encryption for JMX monitoring

Default value

No default value

Required parameter

Optional

This parameter can have two values: true or false. If set on true, then a JMX client will connect to the JMX monitoring through a SSL/TLS encrypted connection. The use of an encrypted connection is especially recommended for JMX remote monitoring from an insecure network, including Internet.

If this parameter is set on true, then the address used by the parameter MonitorJMX.Listen must have a certificate entry in the keystore file defined by the parameter KeyStore. The certificate entry of the keystore must be created with the alias jmx as explained in the description of the KeyStore parameter.

Secure JMX monitoring over insecure networks

In this subsection it is assumed that the JMX client is jconsole. For other JMX clients you can also use the steps below, but you may have to adapt the configuration to suit your specific JMX client.

Supposing the file name of the keystore defined by the KeyStore parameter is mykeystore.jks, and supposing the keystore mykeystore.jks includes an certificate entry for the address used in the configuration of the parameter MonitorJMX.Listen having as alias jmx. Then, use the following steps to establish a secure JMX connection:

  1. Create a truststore for the JMX client. The truststore is a special keystore that can verify the trusted SSL certificates. The trustsore will be used by the JMX client. Supposing that the file name used for the truststore is mytruststore.jks, run the following two commands to create the truststore:

    keytool -export \
    -alias jmx \
    -keystore mykeystore.jks \
    -rfc -file temp.cer
    
    keytool -import \
    -alias jmx \
    -file temp.cer \
    -keystore mytruststore.jks
    

    For the first command, use the password of the keystore as defined by the KeyStorePassword parameter. For the second command, use a new password, say mytruststore-password.

  2. Generate a new keystore for the JMX client having a certificate entry with the alias jmx as follows:

    keytool -genkeypair \
    -alias jmx \
    -keyalg RSA \
    -validity 3600 \
    -keystore clientkeystore.jks
    

    where clientkeystore.jsk is the name of the new keystore. For this command, use a new password, say clientkeystore-password.

  3. To securely connect to the JMX monitoring service of the MigratoryData server, execute the following command:

    jconsole \
    -J-Djavax.net.ssl.keyStore=clientkeystore.jks \
    -J-Djavax.net.ssl.keyStorePassword=clientkeystore-password \
    -J-Djavax.net.ssl.trustStore=mystruststore.jks \
    -J-Djavax.net.ssl.trustStorePassword=mytruststore-password
    

MonitorHTTP.Listen

Description

Address to listen for used to listen for HTTP monitoring clients

Default value

No default value

Required parameter

Optional

The format of the address used by this parameter is the same like the format of the Listen parameter.

Caution

In order to access the HTTP monitoring from a remote machine, please check your firewall settings so that the network traffic from the remote machine is allowed to the address configured by this parameter.

Accessing the HTTP Monitoring Service

Supposing you have the following monitoring related configuration:

Monitor = HTTP
MonitorUsername = admin
MonitorPassword = pass
MonitorHTTP.Listen = push.example.com:4000
MonitorHTTP.Authentication = true
MonitorHTTP.Encryption = false

Then you can access the HTTP monitoring using the following URL:

http://push.example.com:4000/stats?username=admin&password=pass

Opening the URL above will produce an output with the following format:

<fieldname1>:<value1> <fieldname2>:<value2> ... <fieldnameN>:<valueN>

where each field correspond to one of the following stats:

  • Average

  • Standard Deviation

  • Maximum

applied to one of the following metrics:

  • The number of connected clients

  • The number of connections per second

  • The number of disconnections per second

  • The number of incoming messages per second received from publishers

  • The number of outgoing messages per second sent to clients

  • The number of incoming bytes per second received from publishers

  • The number of outgoing bytes per second sent to clients

for one of the following period of time:

  • Current

  • Since startup

  • Last minute, last 5 minutes, and last 15 minutes

  • Last hour, last 5 hours, and last 15 hours

  • Last day, last 5 days, and last 15 days

  • Last month, last 5 months, and last 15 months

XML and JSON Output Format

You can also retrieve data in XML and JSON format. Append a view parameter to the URL above with the value xml or json. For example, to retrieve the monitoring data in XML format use:

http://push.example.com:4000/stats?username=admin&password=pass&view=xml
Filters

You can filter the monitoring data by indicator and/or stats and/or period of time. To do so, add to the URL above one or more of the GET parameters listed in filters table below.

For example, to retrieve the maximum number of concurrent clients in the last 15 minutes, use:

http://push.example.com:4000/stats?username=admin&password=pass&indicator=ConnectedSessions&statistic=MAX&period=Last.15.Minute

Another example. To retrieve the average for all indicators for all available periods of time, use:

http://push.example.com:4000/stats?username=admin&password=pass&statistic=AVG

Parameter

Possible Value

Description

indicator

ConnectedSessions

Number of connected clients

InBytesPerSecond

Number of incoming bytes/second

InPublishMessagesPerSecond

Number of incoming messages/second

OutBytesPerSecond

Number of outgoing bytes/second

OutPublishMessagesPerSecond

Number of outgoing messages/second

SessionConnectionsPerSecond

Number of connections/second

SessionDisconnectionsPerSecond

Number of disconnections/second

statistic

AVG

Average

STDEV

Standard Deviation

MAX

Maximum

period

Current

Current

Last.1.Minute

Last 1 minute

Last.5.Minute

Last 5 minutes

Last.15.Minute

Last 15 minutes

Last.1.Hour

Last 1 hour

Last.5.Hour

Last 5 hours

Last.15.Hour

Last 15 hours

Last.1.Day

Last 1 day

Last.5.Day

Last 5 days

Last.15.Day

Last 15 days

Last.1.Month

Last 1 month

Last.5.Month

Last 5 months

Last.15.Month

Last 15 months

SinceStartup

Since startup

Secure HTTP monitoring over insecure networks

To securely monitor MigratoryData Server over an insecure network such as Internet, configure

MonitorHTTP.Encryption = true

See the description of the MonitorHTTP.Encryption parameter for more details, then access the HTTP monitoring service using over https as follows:

https://push.example.com:4000/stats?username=user&password=pass

MonitorHTTP.Authentication

Description

Specify whether or not to use authentication for HTTP monitoring

Default value

No default value

Required parameter

Optional

This parameter can have two values: true or false. If set on true then, in order to access the HTTP monitoring, you should use the monitoring user name specified with the MonitorUsername parameter and the monitoring password specified with the MonitorPassword parameter.

MonitorHTTP.Encryption

Description

Specify whether or not to use encryption for HTTP monitoring

Default value

No default value

Required parameter

Optional

This parameter can have two values: true or false. If set on true, then an HTTP client will connect to the HTTP monitoring through a SSL/TLS encrypted connection. The use of an encrypted connection is especially recommended for HTTP remote monitoring from an insecure network, including Internet.

If this parameter is set on true, then the address used by the parameter MonitorHTTP.Listen must have a certificate entry in the keystore file defined by the parameter KeyStore.

LogFolder

Description

The folder where the logs will be written

Default value

logs

Required parameter

Optional

If not configured, MigratoryData Server will use the default folder logs relative to the directory path used to start MigratoryData Server.

The log folder can be configured using absolute paths as follows:

LogFolder = /some/path/mylogs

For Linux/Unix

LogFolder = C:/some/path/mylogs

For Windows

LogLevel

Description

The verbosity level of the logs

Default value

INFO

Required parameter

Optional

The following levels are available:

  • TRACE (most verbose)

  • DEBUG

  • INFO (recommended for production use)

  • WARN

  • ERROR (least verbose)

LogRotateLimit

Description

The maximum size of a log file

Default value

10 MB

Required parameter

Optional

The value of this parameter can be expressed in gigabytes, megabytes, and kilobytes by using the following postfixes: GB for gigabytes, MB for megabytes, or KB for kilobytes.

If the log file reaches the size provided by this parameter, then the MigratoryData server will automatically create a new log file. The previous log files are preserved on disk up to the number of log files defined by the LogRotateFileCount parameter.

LogRotateTime

Description

The period of time at which a new log file will be created

Default value

No default value

Required parameter

Optional

The value of this parameter can be expressed in expressed in minutes (m), hours (h), days (D), weeks (W), months (M), or years (Y).

For example, in order to record the logs in a separate file every day use:

LogRotateTime = 1 D

To record the logs in separate file every 4 hours use:

LogRotateTime = 4 h

The previous log files are preserved on disk up to the number of log files defined by the LogRotateFileCount parameter.

Note

This parameter takes precedence over the parameter LogRotateLimit. Therefore, if this parameter is configured, then the parameter LogRotateLimit is ignored.

LogRotateFileCount

Description

Limit the number of historical log files created by log rotation

Default value

100

Required parameter

Optional

If the number of log files produced by log rotation defined by the parameters LogRotateTime or LogRotateLimit reaches the value of this parameter, then the oldest log file is removed whenever a new log file is created such that the total number of logs files will not exceed the value of this parameter.

DocumentRoot

Description

Set the folder from which MigratoryData Server will serve files

Default value

html

Required parameter

Optional

This parameter is optional. If not supplied, the default folder html relative to the directory path used to start the MigratoryData server is used.

Important

MigratoryData Server has a limited capability to serve files. This feature is only offered to facilitate the development process. MigratoryData Server is designed exclusively for real-time messaging.

Thus, for any production deployment, this parameter should be disabled, and a regular web server such as Nginx or Apache should be used for serving files such as web pages and images.

ClusterPassword

Description

The password for inter-cluster communication

Default value

No default value

Required parameter

Required

The servers of a MigratoryData cluster communicate with each other. The password defined by this parameter is used to prevent unauthorized interference into the inter-cluster communication.

Note

This password is used only for inter-cluster communication. It is not used for clients. In order to allow or deny subscriptions and publications for clients, you should enable the entitlement service via the Entitlement parameter.

ClusterDeliveryMode

Description

Specify the quality of the service of the MigratoryData cluster

Default value

Standard

Required parameter

Optional

This parameter is used to define the quality of the service of the MigratoryData cluster. The possible values are:

Standard

Standard Message Delivery

Guaranteed

Guaranteed Message Delivery

Using Standard Message Delivery, in the case of a fail-over reconnection, the client will get the latest retained message available for each of its subscribed subjects.

Using Guaranteed Message Delivery, in the case of a fail-over reconnection, the client will get not only the latest retained message available for each of its subscribed subjects, but also any message received by the cluster during the fail-over period for the subscribed subjects of the client.

ClusterMemberListen

Description

Specify the address to listen for cluster member connections

Default value

No default value

Required parameter

Required

Each server of the MigratoryData cluster communicates with the other members of the cluster, including with itself, along TCP/IP connections. This parameter represents the address used to listen for incoming connections from the other cluster members, including from itself.

The format of the address specified by this parameter is the same like the format of the address specified by the Listen parameter.

Important

The port defined by this parameter must be allowed by the firewall for incoming connections from all the servers of the cluster. In addition, the three consecutive port numbers starting with the port number defined by this parameter must be allowed by the firewall for incoming connections from all servers of the cluster.

For example, supposing that this parameter is configured as follows:

ClusterMemberListen = push.example.com:8801

Then the ports 8801, 8802, 8803, and 8804 must be allowed by the firewall for the internal cluster communication between its members.

ClusterMembers

Description

Define the cluster by specifying its members

Default value

No default value

Required parameter

Required

Each cluster member is specified by its inter-cluster listen address defined by the parameter ClusterMemberListen.

For developing and testing purposes, you could deploy the MigratoryData cluster on the single machine. For example:

ClusterMembers = 192.168.1.1:7701, 192.168.1.1:8801, 192.168.1.1:9901

For production deployments, you should ideally deploy the MigratoryData cluster such that each of its servers will run on a different machine. For example:

ClusterMembers = 192.168.1.1:8801, 192.168.1.2:8801, 192.168.1.3:8801

Important

For each server of the cluster, this parameter should be configured by specifying the list of all cluster members. While there is no restriction on the order of the cluster members, it is mandatory that once you defined a certain order in one server, that order must be preserved for any other server of the cluster. Therefore, the value of this parameter must be identical for each member of the cluster.

ClusterMemberCoordinationFolder

Description

Folder used to store transactional logs related to cluster coordination

Default value

coordination_logs

Required parameter

Optional

If not configured, the default folder coordination_logs relative to the directory path used to start the MigratoryData server will be used.

The coordination log folder can be configured using absolute paths as follows:

ClusterMemberCoordinationFolder = /some/path/coordination_logs

For Linux/Unix

ClusterMemberCoordinationFolder = C:/some/path/coordination_logs

For Windows

Hint

It is strongly recommended to configure this folder on a local disk rather than on a network-attached disk.

Entitlement

Description

Specify the entitlement type

Default value

Basic

Required parameter

Optional

To define which users of your application have access to which subjects, you can define one of the following Entitlement types: None, Basic, or Custom.

  • None allows any client to subscribe to and publish on any subject.

  • Basic allows any client to subscribe to any subject. However, publication is allowed only from the clients which authenticate with the token defined by the parameter EntitlementAllowToken.

  • Custom allows you to define your own entitlement rules. You can use the MigratoryData Extension SDK for Entitlement to build an extension plugin for the MigratoryData server to allow or deny certain users to subscribe to or publish on certain subjects.

EntitlementAllowToken

Description

Specify an entitlement token

Default value

No default value

Required parameter

Required if Entitlement is set on Basic

This parameter applies only if you configure the Entitlement parameter as Basic. See the semantics of this entitlement token in the definition of the entitlement type Basic in the description of the parameter Entitlement.

Advanced Parameters

The advanced parameters of MigratoryData Server are described below.

RunAsUser

Description

Specify the unprivileged (normal) user to run the MigratoryData server

Default value

No default value

Required parameter

Optional

Warning

This parameter is currently supported only for Linux.

For example, if migratorydata is an existing normal user, then you could configure the MigratoryData server to run as a normal user as follows:

RunAsUser = migratorydata

Then, start the MigratoryData server as root (this is necessary to be able to bind on the privileged ports 80 or 443). Please note that while running as root, MigratoryData Server will not accept any client connections. Then, MigratoryData Server will drop the root privileges (using the system call setuid) and will automatically switch to the normal user migratorydata. Only at this time, MigratoryData Server will start to accept client connections.

PublishAllowFromAddressList

Description

Define the list of IP addresses allowed for message publication

Default value

No default value

Required parameter

Optional

If this parameter is configured, then the MigratoryData server will accept message publications only from the clients running on any of the IP addresses defined by this parameter.

If this parameter is not set, message publication will be allowed from any client provided however that the client is allowed by the entitlement rules you define (see the Entitlement parameter).

Note

Please use only dotted-decimal notation for the IP addresses (no DNS names) to specify the list of IP addresses. For example:

PublishAllowFromAddressList = 192.168.1.100, 192.168.1.101

Native.Ssl

Description

Specify whether to use OpenSSL for native TLS/SSL communication

Default value

false

Required parameter

Optional

This parameter can have two values: true or false. If set on true, then the MigratoryData server will use the OpenSSL library for TLS/SSL support. The OpenSSL library provides a better implementation of TLS/SSL in terms of memory and CPU usage compared to the default implementation of Java. While this difference might not be substantial for small or medium MigratoryData deployments, for large MigratoryData deployments with millions of users, it is recommended to use OpenSSL.

Warning

This parameter is currently supported only for Linux. Also, the packages OpenSSL and APR are required to enable the native TLS/SSL communication. See the Installation Guide to learn how to install these packages.

MaxCachedMessagesPerSubject

Description

The number of the most recent messages to be cached

Default value

1000

Required parameter

Optional

For each subject, the MigratoryData maintains an in-memory cache. Messages are removed continuously from the cache of each subject, however each message is held in the cache up to the number of messages defined by this parameter or at least for the number of seconds defined by the parameter CacheExpireTime, whichever comes first..

Important

This parameter applies only if the Guaranteed Message Delivery feature is enabled, see the parameter ClusterDeliveryMode for more details.

CacheExpireTime

Description

The number of seconds to cache a message

Default value

180

Required parameter

Optional

For each subject, the MigratoryData maintains an in-memory cache. Messages are removed continuously from the cache of each subject, however each message is held in the cache up to the number of messages defined by the parameter MaxCachedMessagesPerSubject or at least for the number of seconds defined by this parameter, whichever comes first.

Important

This parameter applies only if the Guaranteed Message Delivery feature is enabled, see the parameter ClusterDeliveryMode for more details.

Workgroups

Description

The number of groups of clients

Default value

The number of total CPU cores available

Required parameter

optional

In order to better scale on multiprocessor hardware the incoming users are separated in groups. This parameter configures the number of groups (every group has a dedicated thread). If not supplied the total CPU cores available is the default value. In most situations it is not recommended to modify the default value.

IoThreads

Description

The number of threads used for I/O processing

Default value

The number of total CPU cores available

Required parameter

Optional

If not supplied the number of total CPU cores available is the default value. In most situations it is not recommended to modify the default value.

Stats.LogInterval

Description

Specify the time interval in seconds to log various statistics

Default value

60

Required parameter

Optional

The minimum value of this parameter is 5 seconds.

MaxBatchingSpace

Description

The maximum size of the batching in bytes

Default value

0

Required parameter

Optional

See the Architecture Guide to learn about batching before configuring this parameter. If this parameter is not configured or configured with the default value 0, then batching is disabled.

MaxBatchingTime

Description

The maximum time of the batching in milliseconds

Default value

0

Required parameter

Optional

See the Architecture Guide to learn about batching before configuring this parameter. If this parameter is not configured or configured with the default value 0, then batching is disabled.

CipherListEnabled

Description

Enable one or more SSL ciphers besides the default JVM ciphers

Default value

No default value

Required parameter

Optional

The JVM supports a number of ciphers. Some of these ciphers are enabled by default. Use this parameter to enable one or more supported ciphers not enabled by default. For example:

CipherListEnabled = TLS_DHE_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_DSS_WITH_AES_128_CBC_SHA

CipherListExcluded

Description

Exclude one or more SSL ciphers from the default JVM ciphers

Default value

No default value

Required parameter

Optional

The JVM supports a number of ciphers. Some of these ciphers are enabled by default. Use this parameter to enable one or more supported ciphers not enabled by default. For example:

CipherListEnabled = TLS_DHE_RSA_WITH_AES_128_CBC_SHA, TLS_DHE_DSS_WITH_AES_128_CBC_SHA

MaxMessageSize

Description

The maximum message size in bytes

Default value

65536 (64 KB)

Required parameter

Optional

This parameter specifies the maximum message size – in bytes – that the MigratoryData server will accept. A client which sends a message larger than this size will be automatically disconnected.

MaxBandwidthRate

Description

Specifies the maximum bandwidth rate in megabytes/second

Default value

0

Required parameter

Optional

This parameter specifies the maximum bandwidth rate – in megabytes per second (MB/s) – that the MigratoryData server is allowed to consume from the available network bandwidth capacity to push messages to clients. If zero is specified, the bandwidth rate will not be limited (this is the default value).

This parameter is particularly useful for use cases where, occasionally, the outgoing message throughput is higher than the available network bandwidth capacity. Supposing the MigratoryData server is installed on a machine with a network bandwidth capacity of a 1 Gbps (i.e. 125 MB/s), and supposing there are one or more large messages to be delivered to a large number of users, producing an outgoing data volume of 1250 MB. By configuring this parameter at 125 MB/s, the assumed available network capacity, the MigratoryData server will be able to deliver that volume of data during 10 seconds, and then operate normally, with low message latency. Otherwise, without configuring this parameter, the system might be severely impacted - as the capacity of the kernel’s socket buffers could be exhausted.

Note that configuring this parameter could be useful not only for the use cases discussed above. It can be used as a protection against the deliberate or accidental exceeding of the available network bandwidth capacity for any other use case.

For most cases, this parameter should be configured to be equal to the available network bandwidth capacity.

Note

With a LAN-based deployment, this parameter can be configured at 125 (MB/s) on a 1 GbE network, and respectively at 1250 (MB/s) on a 10 GbE network. However, with an Internet-based deployment, please check with your network provider to determine the bandwidth capacity available for your deployment.

Extension.Presence

Description

Specify whether to enable the presence extension or not

Default value

false

Required parameter

Optional

Set this parameter on true to enable the presence extension plugin built with the MigratoryData Extension SDK for Presence and deployed under the folder extensions of your MigratoryData installation.

Extension.Presence.Subject

Description

Subject used to replicate presence updates across the cluster

Default value

/__migratorydata__/presence

Required parameter

Optional

Whenever a user connects to or disconnects from a cluster member, a presence update is provided to the presence extension of that cluster member. Moreover, this presence update is replicated across the cluster such that the presence update to be provided to the presence extension of each cluster member.

Internally, MigratoryData uses its client library to replicate presence updates across the cluster. Each cluster member subscribes to the subject defined by this parameter. Whenever a user connects to or disconnects from a cluster member, that cluster member publishes a presence update on the subject defined by this parameter.

Extension.Presence.EntitlementToken

Description

Entitlement token used for presence replication

Default value

the value of the parameter EntitlementAllowToken

Required parameter

Optional

As detailed in the description of the parameter Extension.Presence.Subject, MigratoryData replicates presence updates across the cluster.

The default value of this parameter is the value of the parameter EntitlementAllowToken. In this way, if the value of the parameter Entitlement is Basic or None, then there is no need to configure this parameter, simply use its default value. Otherwise, if the value of the parameter Entitlement is Custom, then your custom entitlement rules should entitle subscriptions and publications on the subject defined by the parameter Extension.Presence.Subject for the connections using the entitlement token defined by this parameter.

Extension.Audit.Access

Description

Specify whether to enable the audit access logs or not

Default value

false

Required parameter

Optional

Set this parameter on true to enable the audit access logs. If the audit extension plugin built with the MigratoryData Extension SDK for Audit and deployed under the folder extensions of your MigratoryData installation is not already enabled, then configuring this parameter on true will also enable the audit extension plugin as well.

Extension.Audit.Cache

Description

Specify whether to enable the audit cache logs or not

Default value

false

Required parameter

Optional

Set this parameter on true to enable the audit cache logs. If the audit extension plugin built with the MigratoryData Extension SDK for Audit and deployed under the folder extensions of your MigratoryData installation is not already enabled, then configuring this parameter on true will also enable the audit extension plugin as well.

Extension.Audit.Message

Description

Specify whether to enable the audit message logs or not

Default value

false

Required parameter

Optional

Set this parameter on true to enable the audit message logs. If the audit extension plugin built with the MigratoryData Extension SDK for Audit and deployed under the folder extensions of your MigratoryData installation is not already enabled, then configuring this parameter on true will also enable the audit extension plugin as well.

Extension.Audit.Stats

Description

Specify whether to enable the audit stats logs or not

Default value

false

Required parameter

Optional

Set this parameter on true to enable the audit stats logs. If the audit extension plugin built with the MigratoryData Extension SDK for Audit and deployed under the folder extensions of your MigratoryData installation is not already enabled, then configuring this parameter on true will also enable the audit extension plugin as well.