PreEmptive Analytics Data Hub User Guide

RabbitMQ

The Data Hub uses the third-party RabbitMQ messaging system to store messages before they are dispatched. The default configuration, where an instance of RabbitMQ is installed on the same machine as the Data Hub, should typically not need to be changed. However, if you need to change e.g. the host or port that they use to communicate, instructions for doing so have been provided here and in the subsections below.

WARNING: Changes to the connection settings must be coordinated across three locations: RabbitMQ, the Endpoint Web Service, and the Dispatch Service. It is easiest and safest to stop all three services (RabbitMQ last), make the changes, and start them again (RabbitMQ first) - see the subsections of Restarting the Entire Data Hub. This will cause a temporary outage at the Endpoint.

Data Hub Parameters

The Data Hub has separate configuration files for the Dispatch Service and for the Endpoint. Each component has the same settings, described below, located in the <appsettings> section of their respective file.

The Endpoint Web Service settings are in [Application folder]\Web\Endpoint\Web.config.

The Dispatch Service settings are in [Application folder]\DispatchService\HubDispatchService.exe.config.

The settings are as follows:

  • RabbitServerAddress
    • The IP or hostname of the RabbitMQ instance.
    • Default: 127.0.0.1
  • RabbitServerPort
    • The port on which AMQP (data transfer) connections are made.
    • Default: 5672 (the AMQP default)
  • RabbitServerPortalPort
    • The port on which RabbitMQ management plugin connections are made.
    • Default: 15672
  • RabbitServerVirtualHost
    • The virtual host on the RabbitMQ server to use.
    • Default: /
  • RabbitServerUsername
  • RabbitServerPassword
    • The password which is used for the above user.
    • This user must have a password.
    • Default: guest
  • QueuingTimeoutInSeconds
    • Time, in seconds, that Data Hub will wait for RabbitMQ to complete an action before giving up and logging an error and incrementing the RabbitMQ Operation Failure WMI counter.
    • Endpoint Web Service will wait for this amount of time for RabbitMQ to enqueue a message before sending a 500 response back to the client.
    • Default: 30
  • QueueCountMonitoringIntervalSeconds
    • The frequency, in seconds, at which the Data Hub will query RabbitMQ to measure queue sizes for reporting as WMI counters.
    • Default: 1
  • BlockedStateTimeoutInSeconds
    • Time, in seconds, that Data Hub will wait for RabbitMQ to clear its alarm state during which all publishing is blocked before trying to publish again. This is only a fail safe in case RabbitMQ crashes and never sends a shutdown notification or an alarm cleared notification. In most cases, this setting should be left to the default of 1800 (30 minutes).
    • Default: 1800

RabbitMQ Parameters

The Data Hub-provided installation of RabbitMQ has been pre-configured to work with the Data Hub. The relevant connection settings are in the RabbitMQ configuration file, which is in the non-standard location of [RabbitMQ data folder]\rabbitmq.config.

Details about the RabbitMQ configuration settings can be found in the online documentation for the RabbitMQ configuration file.

These settings can be changed using JSON syntax.

Parameters include:

  • rabbit.tcp_listeners
    • An array of interfaces RabbitMQ will listen on for AMQP connections, each expressed in the form {hostname, port}.
    • The default install limits RabbitMQ access to the loopback address. Changing this setting to a public interface may be a security risk, especially if the default user guest has not been removed.
    • Pre-configured setting: {"127.0.0.1", 5672}.
  • rabbit.collect_statistics_interval
    • The time, in milliseconds, between RabbitMQ updating its statistical tracking (e.g. the size of queues).
    • Pre-configured setting: 1000.
  • rabbitmq_management.listener.ip
    • The IP for the RabbitMQ management plugin to listen on.
    • The default install limits RabbitMQ access to the loopback address. Changing this setting to a public interface may be a security risk, especially if the default user guest has not been removed.
    • Pre-configured setting: 127.0.0.1.
  • rabbitmq_management.listener.port
    • The port for the RabbitMQ management plugin to listen on.
    • Pre-configured setting: 15672.

RabbitMQ Users

There are three types of RabbitMQ users this documentation describes:

  • Monitoring User: Can see statistics on RabbitMQ, but cannot make any changes to the user configuration, nor affect the queues in any way.
  • Application User: Can read from and write to queues, but cannot make any changes to the user configuration.
  • Admin User: Can modify all elements of RabbitMQ, including changing the user configuration and purging queues.

The default install contains only one user, an admin user named guest (with a password of guest). Both the Endpoint Web Service and Dispatch Service are configured for this user by default.

Adding a User

To create a user:

  1. Using a web browser, browse to http://localhost:15672/#/users.
  2. Log in using an admin user (guest with a password of guest is the default admin user).
  3. Locate the Add a user section. Expand if necessary.
  4. Enter a Username and Password. Make sure to record these credentials in compliance with your organization's security policy.
  5. Select the appropriate tag depending on the user type:
    • For a monitoring user, click [Monitoring].
    • For an application user, click [Management].
    • For an admin user, click [Admin].
  6. Click Add user.
  7. Locate the All users section. Expand if necessary.
  8. Click on the name of the user you just created.
  9. Locate the Permissions section. Expand if necessary.
  10. Under Set permission, choose the appropriate virtual host (/ by default).
  11. Configure the Configure regexp, Write regexp, and Read regexp fields depending on the user type:
    • For a monitoring user, clear the fields entirely.
    • For other users, ensure each field is set to .*.
  12. Click Set permission.

Removing a User

Warning: You must reconfigure the Data Hub connections to use another admin or application user before removing the user currently used by the Data Hub (default is guest).

Warning: Do not remove all admin users. If you do so, you will probably have to uninstall and reinstall, causing data loss.

To remove a user:

  1. Using a web browser, browse to http://localhost:15672/#/users.
  2. Log in using an admin user.
  3. Locate the All users section. Expand if necessary.
  4. Click on the name of the user you wish to remove.
  5. Locate the Delete this User section. Expand if necessary.
  6. Click Delete.
  7. Confirm that you wish to permanently delete the user.


Data Hub Version 1.5.0. Copyright © 2015 PreEmptive Solutions, LLC