The core parameters of the 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. To obtain a license key, please contact MigratoryData at support@migratorydata.com.

Memory

   
Description Specify the maximum memory to be used by MigratoryData
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, configure the parameter Memory as follows:

Memory = 512 MB

In a production environment it is recommended to use at least 8 GB or more depending on the load of data on the server and how many 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 will bind only to that IP address. The wildcard address (*) will enable MigratoryData to bind to all available IP addresses of the machine.

If MigratoryData 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.

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 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, 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).

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 with 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

  3. for the this new file must be the same as that used for the keystore.

  4. 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.

  5. 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, HTTP, and Prometheus. Use comma separated values to configure multiple monitoring options. For example, to configure JMX and Prometheus, use the following configuration:

Monitor = JMX, Prometheus
Prometheus monitoring is usually combined with Grafana dashboarding. Please check out the article Monitoring MigratoryData with Prometheus and Grafana for more information.

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
- MonitorPrometheus.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
- MonitorPrometheus.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 as the format of the Listen parameter.

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. There are also many commercial tools that can be used for JMX that provide enhanced functionality like dashboards and database persistence.

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 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 MigratoryData. To fix this issue, edit /etc/hosts so that hostname resolves to the address used by MonitorJMX.Listen.

To access the JMX service of MigratoryData 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 a certificate entry for the address used in the configuration of the parameter MonitorJMX.Listen having as alias jmx, 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 MigratoryData, 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 as the format of the Listen parameter.

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 corresponds 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 periods 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 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.

MonitorPrometheus.Listen

   
Description Address to listen for Prometheus monitoring clients
Default value No default value
Required parameter Optional

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

In order to access the Prometheus 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.

MonitorPrometheus.Authentication

   
Description Specify whether or not to use authentication for Prometheus 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 Prometheus monitoring, you should use the monitoring user name specified with the MonitorUsername parameter and the monitoring password specified with the MonitorPassword parameter.

MonitorPrometheus.Encryption

   
Description Specify whether or not to use encryption for Prometheus monitoring
Default value No default value
Required parameter Optional

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

If this parameter is set on true, then the address used by the parameter MonitorPrometheus.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 prometheus as explained in the description of the KeyStore parameter.

LogFolder

   
Description The folder where the logs will be written
Default value logs
Required parameter Optional

If not configured, MigratoryData 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 MigratoryData 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 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 a 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 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 is used.

MigratoryData has a limited capability to serve files. This feature is only offered to facilitate the development process. MigratoryData 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.

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](#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 as the format of the address specified by the Listen parameter.

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
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.

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
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 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.
  • JWT allows clients to subscribe and publish based on JWT tokens using the MigratoryData JWT Authorization add-on. To start using JWT authorization with MigratoryData, please read the JWT Authorization add-on documentation.
  • Custom allows you to define your own entitlement rules. You can use the Server Extensions API to build an extension for MigratoryData to authorize 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.