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 Core Parameters and Advanced Parameters below.
Using Environment Variables
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 of a parameter 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
.
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
Description | A string representing the license key |
Default value | No default value |
Required parameter | Required |
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.
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.
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.
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, 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).
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:
-
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, sayintermediary.crt
. Then append the certificate signing request that you sent to the CA authority, saypush.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
-
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. -
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 alias1
. -
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.
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.
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 the note of the section MIGRATORYDATA_JAVA_EXTRA_OPTS.
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:
-
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
. -
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, sayclientkeystore-password
. -
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 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.
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.
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.
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.
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.
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
ClusterSeedMemberCount
Description | Define the number of seed members to be used for clustering |
Default value | The default number of seed members are as follows: 3 for clusters with three or four members 5 for clusters with five or more members |
Required parameter | Optional |
For clustering using Guaranteed Message Delivery (see
ClusterDeliveryMode), this parameter defines the
number of seed members to be used for the cluster. The possible values
for this parameter are 3
and 5
.
For most cases, it is sufficient to use the default value of this parameter.
See the elasticity feature to learn about elasticity and seed member before configuring this parameter.
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 = /path/coordination_logs |
For Linux/Unix |
ClusterMemberCoordinationFolder = C:/path/coordination_logs |
For Windows |
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 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 |
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).
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.
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..
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.
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. The format of the
stats logs is as follows:
[timespamp] [S] [INFO] [STATS] {
connectedSessions,\
connectedSessionsWeb,\
connectedSessionsMobile,\
connectedSessionsDesktop,\
sessionConnectionsPerSecond,\
sessionDisconnectionsPerSecond,\
inPublishMessagesPerSecond,\
outPublishMessagesPerSecond,\
inBytesPerSecond,\
outBytesPerSecond,\
clientInPublishMessagesPerSecond,\
connectRateRecoverySuccessPerSecond,\
connectRateRecoveryFailPerSecond,\
clientPublishFailedPerSecond\
}
MaxBatchingSpace
Description | The maximum size of the batching in bytes |
Default value | 0 |
Required parameter | Optional |
See the batching feature 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 batching feature 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 |
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 |
Use this parameter to exclude one or more ciphers 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 number of bytes a message should have (including the protocol overhead) to be accepted by the MigratoryData server. A client which sends a message larger than this size will be automatically disconnected.
NOTIFY_MESSAGE_SIZE_LIMIT_EXCEEDED
.
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.
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.