RabbitMQ Server Installation

Introduction

These are the installation instructions for vFabric RabbitMQ Server. Each platform installation requires Erlang, which provides the runtime RabbitMQ plus supporting services such as the Mnesia DBMS and logging.

vFabric RabbitMQ also requires the presence of a version 1.6 Java Runtime Environment (JRE) or Java Development Kit (JDK).

Management scripts are provided to start and stop the broker, and set up a default environment. Scripts and commands need to run as a privileged user, e.g. an administrator on Windows or a user with root permission (sudo) on Unix-like systems.

If you use non-default file locations, ports, account or service names, or component properties these should be configured. If you need multiple server nodes see the clustering guide.

Installing as Part of vFabric Cloud Application Platform

vFabric RabbitMQ is available as a standalone product and as part of vFabric Cloud Application Platform, a set of runtime components that let you build, scale, and run modern, agile applications in virtual environments.

If you obtain RabbitMQ standalone, you can install it on both physical and virtual machines according to the procedures in this document.

If you obtain RabbitMQ as part of an Advanced vFabric Platform package, you install it exclusively on VMware virtual machines that run on vSphere. The platform install process adds the vFabric License Server to an existing vCenter server. The vFabric License Server accepts a network license, actually a pool of licenses for vFabric components, which makes it easy to manage the licensing of all components installed on the VMs.

If you obtain RabbitMQ as part of vFabric Platform, first complete the license activation and installation procedures in the Getting Started with vFabric Cloud Application Platform guide in this Documentation Center. Then follow procedures in this document to install RabbitMQ and complete any remaining RabbitMQ-specific installation and configuration tasks.

Windows

Verifying the Installation

If you installed vFabric RabbitMQ to run as a Windows service you can check the status of RabbitMQ through the services control panel.

Go to Start > Run (or press Windows-R) and then type: services.msc and press enter.

Scroll down the list of services until you find the entry for RabbitMQ. In the status column, you should see the text "Started".

If you want to check the status of RabbitMQ using the command line open a command prompt and change directory to your RabbitMQ installation (see footnote #2).

Type the following command:

rabbitmqctl status
          

You should see something like the following output:

Status of node 'rabbit@host' ...
  [{pid,...},
   {running_applications,[{rabbit,"RabbitMQ","2.4.1"},
                          {os_mon,"..."},
                          {sasl,"..."},
                          {mnesia,"..."},
                          {stdlib,"..."},
                          {kernel,"..."}]},
  {nodes,{disc,['rabbit@host']}]},
  {running_nodes,['rabbit@host']}]
           

If you have problems please read the troubleshooting section of this guide.

Finding Command Scripts and App Data

Commands for RabbitMQ Server

Within the rabbitmq_server-2.4.1\sbin directory are scripts that can be used to control the RabbitMQ server. Note that the RabbitMQ server can be run as either an application or service.

Note: On later versions of Window you need to run these scripts from a command prompt with elevated privileges.

Find Commands Easily

Set up the system path so you can find the server and sbin directory easily.

  • Create a system environment variable (e.g. RABBITMQ_SERVER) for "C:\Program Files\RabbitMQ\rabbitmq_server-2.4.1". Adjust this if you put rabbitmq_server-2.4.1 elsewhere or if you upgrade versions.
  • Append the literal string ";%RABBITMQ_SERVER%\sbin" to your system path environment variable.
Now you can run rabbitmq commands from any (administrator) Command Prompt.

You will need to navigate to rabbitmq_server-2.4.1\sbin to run commands if your system path does not contain the RabbitMQ sbin directory.

Finding Application Data

By default, the RabbitMQ logs and Mnesia database are stored in the current user's Application Data directory e.g. C:\Documents and Settings\User\Application Data or C:\Documents and Settings\User\AppData\Roaming (Windows Vista).

Execute echo %APPDATA% at a Command Prompt to find this directory. Alternatively, Start > Run %APPDATA% will open this folder.

Running RabbitMQ Server as an Application

The application is started by the rabbitmq-server.bat script in sbin.

Customise RabbitMQ Server Environment Variables

Environment variable defaults are set within the rabbitmq-server.bat file. You may need to customise environment variables for your installation.

Start the Broker as an Application

Run the command

rabbitmq-server -detached
Alternatively, you can double-click the rabbitmq-server.bat file in Windows Explorer.

If you start by double-clicking, a Command Prompt window opens, displays a banner message, reports on progress in the startup sequence, and concludes with "broker running". This shows that the RabbitMQ broker has been started successfully.

If you started without the -detached option, e.g. by double-clicking, you will need a second command prompt window to control the application cleanly. Closing the original command prompt will forcefully shut down a server started this way.

Stop or Manage the Broker

rabbitmq-server only starts the broker. Use rabbitmqctl commands to manage the broker.

Running RabbitMQ Server as a Service

The service will run in the security context of the system account without the need for a user to be logged in on a console. This is normally more appropriate for production use. The server should not be run as a service and application simultaneously.

The service runs using the rabbitmq-service.bat script in sbin.

Customise RabbitMQ Service Environment Variables

Note: After setting environment variables, you may need to install the service again.

The rabbitmq-service.bat script recognises many of the same environment variables as rabbitmq-server.bat, as well as a few additional service environment variables.

Install the Service

Install the service by running

rabbitmq-service install

A service with the name defined by RABBITMQ_SERVICENAME should now appear in the Windows Services control panel (Start > Run services.msc).

Managing the Service

To manage the service (install, remove, start, stop, enable, disable), use rabbitmq-service.bat commands. Refer to the service guide for more information and troubleshooting guidance. You can also use the Windows Services panel (services.msc) to perform some of the same functions as the service script.

Start the Broker as a Service

To start the broker, execute

rabbitmq-service start

If the output from this command is "Service RABBITMQ_SERVICENAME started", then the service was started correctly.

Confirm the service named RABBITMQ_SERVICENAME reports a "Started" status in Services:
Start > Run services.msc.

Manage the Broker

To manage the broker use rabbitmqctl commands.

RPM-based Linux (RHEL / CentOS)

Installing RabbitMQ Server

Register with RHN

rhn_register

On RHEL 6, you also need to edit /etc/yum/repos.d/rhel-beta.repo. On each repository:

  • change enable to 1 from 0
  • change https to http

Setup the EPEL repository

Enable EPEL on your machine. Instructions are in the EPEL FAQ.

Install Erlang

On RHEL 5, and derived distributions, the version of Erlang in the EPEL repository (R12B-5) is relatively old. Although RabbitMQ will run on this version, performance may be impaired relative to more recent versions and certain non-core features are not supported (e.g. management plug-in). We recommend installing the most recent stable version of Erlang, which is made available by the owner of the EPEL Erlang package, as follows:

Set up the fedorapeople repository. As root, invoke:
wget -O /etc/yum.repos.d/epel-erlang.repo http://repos.fedorapeople.org/repos/peter/erlang/epel-erlang.repo

Install (or update) Erlang with:
yum install erlang

Install Java

Find and install a 1.6 version JRE or JDK.

Install the vFabric EULA

rpm -Uvf vfabric-eula-5.0.0-10.noarch.rpm

Install vFabric RabbitMQ Server

rpm -Uvf vfabric-rabbitmq-server-2.4.1-1.fedora.noarch.rpm

Running RabbitMQ Server

Customise RabbitMQ Environment Variables

The server should start using defaults. However, you can customise the RabbitMQ environment if you so wish. Also, see how to configure components.

Start the Server

The server is not started as a daemon by default when the RabbitMQ server package is installed. To start the daemon by default when the system boots, as an administrator run chkconfig rabbitmq-server on.

As an administrator, start and stop the server as usual using /sbin/service rabbitmq-server stop/start/etc.

Note: The server is set up to run as system user rabbitmq. If you change the location of the Mnesia database or the logs, you must ensure the files are owned by this user (and also update the environment variables).

Manage the Server

See the generic Unix section for info on rabbitmqctl commands and logging.

Generic Unix or Linux

Running RabbitMQ Server

Customise RabbitMQ Environment Variables

Within the sbin directory is a shell script rabbitmq-server which uses default values. You can customise the RabbitMQ environment. Also see how to configure components.

Note: If the directories RABBITMQ_MNESIA_BASE and RABBITMQ_LOG_BASE do not exist the server will attempt to create them. The server needs write permission at the configured locations.

Start the Server

Invoke the rabbitmq-server shell script as the user you wish to run the server as. Be sure that the user's environment has a JAVA_HOME environment variable set pointing to a valid 1.6 Java runtime on your system. This displays a banner message, and reports on progress in the startup sequence, concluding with the message "broker running", indicating that the RabbitMQ broker has been started successfully.

You can also start the server in "detached" mode with rabbitmq-server -detached, in which case the server process runs in the background.

Activate a Local vFabric RabbitMQ License

When you purchase a local production vFabric RabbitMQ license, your account manager provides you with one or more serial numbers. This section describes how to activate this local license.

Note: This section does not apply if you installed RabbitMQ as part of vFabric Cloud Application Platform; for information on how to activate a network license, see Installing as Part of vFabric Cloud Application Platform.

1. On the computer on which you will run vFabric RabbitMQ server, paste the serial number into a file named vf.rmq-serial-numbers.txt.

2. Save this file to the directory appropriate to your operating system:

  • Windows: %ALLUSERSPROFILE%\VMware\vFabric\
  • Linux/Unix: /etc/opt/vmware/vfabric/

3. Ensure that the file is readable by the user who runs vFabric RabbitMQ server.

Troubleshooting

Checking Broker Status

You can use rabbitmqctl status to verify whether a broker is running.
Normal output from a running broker without plugins follows this pattern:

  Status of node 'rabbit@xxx' ...
  [{running_applications,[{rabbit,"RabbitMQ","2.4.1"},
          {os_mon,"..."},
          {sasl,"..."},
          {mnesia,"..."},
          {stdlib,"..."},
          {kernel,"..."},
  {nodes,[{disc,['rabbit@xxx']}]}
  {running_nodes,['rabbit@xxx']}]

This example indicates that no broker is running:

  Status of node 'rabbit@xxx' ...
  Error: unable to connect to node 'rabbit@xxx': nodedown
  diagnostics:
  - nodes and their ports on xxx: [{rabbitmqctl,...}]
  - current node: 'rabbitmqctlxxx@xxx'
  - current node home dir: [...]
  - current node cookie hash: [...]
If the diagnostic line looks like this:
  - nodes and their ports on xxx: [{rabbit,...},{rabbitmqctl,...}]
and the broker logfile contains entries similar to
  Connection attempt from disallowed node...
then you should make sure the erlang cookies are the same.

Server Fails to Start

When the server fails to start, usually a crash dump file erl_crash.dump is created in the directory where the server was started. This can provide very detailed information on the causes of a start up failure, but its analysis requires Erlang expertise.

If you attempt to start another server while a broker is already running, then you will receive an error report. You can confirm whether the broker is already running by checking the status.

If the server fails to start, examine the console output and the log files in the RABBITMQ_LOG_BASE directory. Configuration and permission errors are frequently the cause, e.g. the Mnesia directory cannot be created.

Windows Service fails to Install
If the service fails to install, check the service account has full access permission for RABBITMQ_BASE, RABBITMQ_MNESIA_BASE and RABBITMQ_LOG_BASE directories [XP, Vista].
Windows Service fails to Start

If the service fails to start, make sure the service has been installed.

On starting the service, if the service output reads "The process terminated unexpectedly" instead, then the service did not start correctly. Check that the environment variables are set correctly. The logfiles in RABBITMQ_BASE may also contain useful diagnostic information.

If the server is not behaving as expected during operation, examine the log files and use the rabbitmqctl commands from the admin guide to obtain further information on the server status.

For problems encountered in the handling of AMQP traffic, the AMQP capture and analysis tool may help in the analysis.

Failing that, it's possible that we've solved the problem for someone else. Try using the search box at the top of our web pages to find site, mailing list and blog information. You might also check our mailing list archives.

If you still can't find a solution to your problem then please post a new message to rabbitmq-discuss@lists.rabbitmq.com (you may have to join the mailing list first). Let us know what you were trying to do, the error you received and relevant entries from the logfile and one of our engineers will help you get it fixed.

If all of the above fails, please tell us about the problem, including the log files under RABBITMQ_LOG_BASE in your report.