Step 3: RabbitMQ Installation

In QMS 9.2 and above the MSMQ component is replaced with RabbitMQ. The RabbitMQ service will need to be installed on the QMS server. In a multi-server environment, only one instance of RabbitMQ needs to be installed (we suggest on the server running the Data Service).

Included with the upgrade package there is a RabbitMQSetup.exe that will install Erlang and RabbitMQ as well as execute he necessary command line entries to create the qmsadmin user with a password of admin and enable the RabbitMQ UI. The RabbitMQSetup.exe is located in the "Installers\Service Installs\RabbitMQ" directory included with the QMS Upgrade zip. Alternatively, you can still install RabbitMQ using the steps below:

QMS uses RabbitMQ 4.3.5 which requires Erlang OTP 28.5.0.6 to be installed first:

https://github.com/erlang/otp/releases/download/OTP-28.5.0.6/otp_win64_28.5.0.6.exe

Then install RabbitMQ 4.3.5:

https://github.com/rabbitmq/rabbitmq-server/releases/download/v4.3.5/rabbitmq-server-4.3.5.exe

Once you have installed Erlang and RabbitMQ you need to create a user in RabbitMQ that QMS can use and enable the RabbitMQ UI. To do this you need to run a few commands from the RabbitMQ install "sbin" folder (using PowerShell or Command Prompt). The default RabbitMQ install sbin directory is C:\Program Files\RabbitMQ Server\rabbitmq_server-4.3.5\sbin but may be different if you installed to a different directory in Windows. Your RabbitMQ username and password can be anything you want, but make a note of it as it will be needed later when running the upgrader.

  1. Create a user and password (example user is "qmsadmin" with password "admin"):

    rabbitmqctl.bat add_user qmsadmin admin

  2. Set tags for the user (example user is "qmsadmin"):

    rabbitmqctl.bat set_user_tags qmsadmin administrator

  3. Set permissions for the user (example user is "qmsadmin"):

    rabbitmqctl.bat set_permissions -p / qmsadmin ".*" ".*" ".*"

  4. Enable the RabbitMQ UI (which can be accessed on the RabbitMQ Server via http://localhost:15672/):

    rabbitmq-plugins enable rabbitmq_management

RabbitMQ with QMS High Availability

In a QMS HA environment it is recommended to install two RabbitMQ instances, one on each data server (primary and secondary). During the upgrade you will need to configure RabbitMQ in QMS (as described in the Step 5: Run Upgrader section).

The following scheme should be adopted for the RabbitMQHostList:

  • Primary Recording Server: RabbitMQHostList contains the address of the primary data server

  • Secondary Recording Server: RabbitMQHostList contains the address of the secondary data server

  • Primary Data Server: RabbitMQHostList contains the address of the primary data server

  • Secondary Data Server: RabbitMQHostList contains the address of the secondary data server

  • All MPS Servers: RabbitMQHostList contains the address of the primary data server followed by the address of the secondary data server, in that order, separated by a semi-colon.

Troubleshooting RabbitMQ Installation

Error: Failed to create cookie file 'h:/.erlang.cookie': enoent

This error can occur if RabbitMQ is unable to access the HOME directory of the server (or the HOME directory has been disabled by policy). Follow these steps to resolve:

  1. Edit C:\Program Files\RabbitMQ Server\rabbitmq_server-4.2.2\sbin\rabbitmq-env.bat

  2. Add the following line at the bottom of the file (you can change the HOME directory to suit):

    set HOMEDRIVE=C:\HOME

  3. Then run these commands from the RabbitMQ instsall "sbin" folder (using PowerShell or Command Prompt) to stop, reinstall and start RabbitMQ:

    rabbitmq-service stop
rabbitmq-service remove
rabbitmq-service install
rabbitmq-service start

Error: unable to perform an operation on node 'rabbit@[SERVERNAME]'

This error can occur if the erlang cookie in the System32 directory is not the same as the cookie in the HOME directory. Follow these steps to resolve:

  1. Copy the file C:\Windows\System32\config\systemprofile\.erlang.cookie into C:\HOME\.erlang.cookie (an alternate location for this file may be C:\Windows\SysWOW64\config\systemprofile\.erlang.cookie)

  2. Restart RabbitMQ using the stop, remove, install, start commands from step 3 above.