Skip to main content
Version: Next

Windows Configuration

This guide is a companion to the main Windows installation guide.

It documents known conditions and scenarios which can cause RabbitMQ Windows service or CLI tools to malfunction.

Anti-virus Software​

Anti-virus and related security software can prevent nodes from accepting or opening network connections, accessing files on disk, and so on. This results in failures that are sporadic and very difficult to reason about.

It is highly recommended that RabbitMQ processes, ports, the Windows service, and node data directory are all excluded from scanning by such tools.

An even better option would to be run RabbitMQ nodes on dedicated hosts with a configured firewall but without any anti-virus software.

Erlang Distribution Port​

To specify a non-standard port to be used for Erlang distribution, do the following:

  • Make sure to use the same administrative user that was used to install RabbitMQ
  • Stop the RabbitMQ Windows service using .\rabbitmq-service.bat stop
  • Remove the RabbitMQ Windows service using .\rabbitmq-service.bat remove
  • Create the %AppData%\RabbitMQ\rabbitmq-env-conf.bat file with the following contents (use your own port number):
set DIST_PORT=44556
  • Install the RabbitMQ Windows service using .\rabbitmq-service.bat install
  • Start the RabbitMQ Windows service using .\rabbitmq-service.bat start
  • Verify what port is being used for inter-node and CLI tool communication:
epmd -names

Multiple Versions of Erlang May Cause Installation Issues​

Due to how the Windows .exe installer detects an installed version of Erlang, RabbitMQ may end up not using the latest version of Erlang installed. Please ensure that only one version of Erlang is installed - the version you wish RabbitMQ to use. If you must upgrade Erlang, use this procedure:

  • Make sure to use the same administrative user that was used to install RabbitMQ
  • Stop the RabbitMQ Windows service using .\rabbitmq-service.bat stop
  • Uninstall Erlang
  • Install the new version of Erlang
  • Open the "RabbitMQ Command Prompt (sbin dir)" start menu item and run the commands below to reinstall the Windows service
.\rabbitmq-service.bat remove
.\rabbitmq-service.bat install
.\rabbitmq-service.bat start

If any environment variables have changed in the mean time, Windows service reinstallation would also be necessary.

Cannot Install to a Path with non-ASCII Characters​

RabbitMQ will fail to start with the error that reads

RabbitMQ: Erlang machine stopped instantly (distribution name conflict?)

when installed to a path with non-ASCII characters in it. This is because we need to pass the location of the compiled Erlang files to the Erlang VM. It expects input in UTF-8, but the console will typically use some other encoding.

Mitigation​

One of these options can be used to mitigate:

  • Override RABBITMQ_BASE to point to a directory that only has ASCII characters and re-install the Windows service.
  • Edit the file rabbitmq-server.bat and change the line set TDP0=%~dp0 to set TDP0=%~dps0. This will use short paths (the infamous C:\PROGRA~1) everywhere.

CLI Tools Display or Parse non-ASCII Characters Incorrectly​

Similarly, RabbitMQ CLI tools will expect command line parameters to be encoded in UTF-8, and display strings as UTF-8. The console will instead provide and expect some country-specific encoding.

Mitigation​

One of these options can be used to mitigate:

  • Avoid using non-ASCII characters in RabbitMQ installation and node directory paths
  • On recent versions of Windows, issue the command 
    chcp 65001
    before using CLI tools to force the console to use UTF-8
  • Where possible, use the management plugin instead of CLI tools.

CLI Tools Show ANSI Character Sequences​

In case the output from rabbitmqctl and other CLI tools looks like this:

←[1mUsage←[0m

rabbitmqctl [--node <node>] [--timeout <timeout>] [--longnames] [--quiet] <command> [<command options>]

Available commands:

←[1mHelp←[0m:

    autocomplete                  Provides command name autocomplete variants
    help                          Displays usage information for a command
    version                       Displays CLI tools version

Mitigation​

Two possible mitigations are:

  1. Pipe rabbitmqctl.bat output through Out-Host, with each command, like so: rabbitmqctl.bat | Out-Host
  2. Globally enable VT/ANSI escape sequences in Command and PowerShell windows: a. in PowerShell: Set-ItemProperty HKCU:\Console VirtualTerminalLevel -Type DWORD 1 b. open a new console window for changes to take effect

For further information, including caveats, see Colored text output in PowerShell console using ANSI / VT100 codes

If RabbitMQ is installed using a non-administrative account, a shared secret file used by nodes and CLI tools will not be placed into a correct location, leading to authentication failures when rabbitmqctl.bat and other CLI tools are used.

Mitigation​

One of these options can be used to mitigate:

  • Re-install RabbitMQ using an administrative user
  • Copy the file .erlang.cookie manually from %SystemRoot% or %SystemRoot%\system32\config\systemprofile to %HOMEDRIVE%%HOMEPATH%.

See How CLI Tools Authenticate to Nodes (and Nodes to Each Other in the CLI guide.

Setting net_ticktime​

Due to how RabbitMQ starts as a Windows service, you can't use a configuration file to set net_ticktime and instead must use an environment variable.

Mitigation​

First, log in using the administrative account you used, or will use, to install RabbitMQ and create the %AppData%\RabbitMQ\rabbitmq-env-conf.bat file with the following contents:

@echo off
set SERVER_ADDITIONAL_ERL_ARGS=-kernel net_ticktime 120

The above will set net_ticktime to 120 seconds.

If you have not yet installed RabbitMQ, the setting will be picked up during installation.

If you have already installed RabbitMQ, open the "RabbitMQ Command Prompt (sbin dir)" start menu item and run these commands:

.\rabbitmq-service.bat stop
.\rabbitmq-service.bat remove
.\rabbitmq-service.bat install
.\rabbitmq-service.bat start