Menu

Installing on Generic Unix

Download the Server

DescriptionDownload  
Generic Unix release (tar.xz, from Bintray) rabbitmq-server-generic-unix-3.7.8.tar.xz(Signature)
Generic Unix release (tar.xz, from GitHub) rabbitmq-server-generic-unix-3.7.8.tar.xz(Signature)

Generic Unix or Linux (BSD, Mac OS X)

Install the Server

Install a supported version of Erlang.

Download rabbitmq-server-generic-unix-3.7.8.tar.xz from one of the links above.

Contained in the tarball is a directory named rabbitmq_server-3.7.8. You should extract this into somewhere appropriate for application binaries on your system. The sbin directory will be found in this directory.

Run RabbitMQ Server

Overview

Unlike some other installation methods, namely the Debian and RPM packages, RabbitMQ generic UNIX binary build does not require sudo. It can be uncompressed into any location and started and managed using the tools under sbin. Default data directory location will be under ./var, that is, in the installation directory.

Start the Server

To start the server, run the sbin/rabbitmq-server script. This displays a short banner message, concluding with the message "completed with [n] plugins.", indicating that the RabbitMQ broker has been started successfully.

To start the server in "detached" mode, use rabbitmq-server -detached. This will run the node process in the background.

Configure the Server

It is possible to customise the RabbitMQ environment by setting environment variables in $RABBITMQ_HOME/etc/rabbitmq/rabbitmq-env.conf. Server components may be configured, too, in the RabbitMQ configuration file located at $RABBITMQ_HOME/etc/rabbitmq/rabbitmq.config. Neither of these files exist after installation.

File Locations

The Generic Unix tarball is designed as far as possible to run without requiring configuration changes or special permissions. The directories and files used by default are all held under the installation directory rabbitmq_server-3.7.8 which is in the $RABBITMQ_HOME variable in the scripts.

Should you wish to install RabbitMQ Server such that it uses the conventional system directories for configuration, database, log files, plugins etc, it is possible to do this.

Find the line:

SYS_PREFIX=${RABBITMQ_HOME}
in the sbin/rabbitmq-defaults script and change this line to:
SYS_PREFIX=
but do not modify any other line in this script.

Note: After this modification the default directory locations may require different permissions. In particular RABBITMQ_MNESIA_BASE and RABBITMQ_LOG_BASE may need to be created (the server will attempt to create them at startup), and the RABBITMQ_ENABLED_PLUGINS_FILE will need to be writable (for rabbitmq-plugins). The configuration files will be looked for in /etc/rabbitmq/.

Port Access

RabbitMQ nodes bind to ports (open server TCP sockets) in order to accept client and CLI tool connections. Other processes and tools such as SELinux may prevent RabbitMQ from binding to a port. When that happens, the node will fail to start. CLI tools, client libraries and RabbitMQ nodes also open connections (client TCP sockets). Firewalls can prevent nodes and CLI tools from communicating with each other. Make sure the following ports are accessible:

  • 4369: epmd, a peer discovery service used by RabbitMQ nodes and CLI tools
  • 5672, 5671: used by AMQP 0-9-1 and 1.0 clients without and with TLS
  • 25672: used for inter-node and CLI tools communication (Erlang distribution server port) and is allocated from a dynamic range (limited to a single port by default, computed as AMQP port + 20000). Unless external connections on these ports are really necessary (e.g. the cluster uses federation or CLI tools are used on machines outside the subnet), these ports should not be publicly exposed. See networking guide for details.
  • 35672-35682: used by CLI tools (Erlang distribution client ports) for communication with nodes and is allocated from a dynamic range (computed as server distribution port + 10000 through server distribution port + 10010). See networking guide for details.
  • 15672: HTTP API clients, management UI and rabbitmqadmin (only if the management plugin is enabled)
  • 61613, 61614: STOMP clients without and with TLS (only if the STOMP plugin is enabled)
  • 1883, 8883: (MQTT clients without and with TLS, if the MQTT plugin is enabled
  • 15674: STOMP-over-WebSockets clients (only if the Web STOMP plugin is enabled)
  • 15675: MQTT-over-WebSockets clients (only if the Web MQTT plugin is enabled)
It is possible to configure RabbitMQ to use different ports and specific network interfaces.

Default user access

The broker creates a user guest with password guest. Unconfigured clients will in general use these credentials. By default, these credentials can only be used when connecting to the broker as localhost so you will need to take action before connecting from any other machine.

See the documentation on access control for information on how to create more users, delete the guest user, or allow remote access to the guest user.

Managing the Broker

To stop the server or check its status, etc., you can invoke sbin/rabbitmqctl (as the user running rabbitmq-server). All rabbitmqctl commands will report the node absence if no broker is running.

  • Invoke rabbitmqctl stop to stop the server.
  • Invoke rabbitmqctl status to check whether it is running.

More info on rabbitmqctl.

Controlling System Limits

RabbitMQ installations running production workloads may need system limits and kernel parameters tuning in order to handle a decent number of concurrent connections and queues. The main setting that needs adjustment is the max number of open files, also known as ulimit -n. The default value on many operating systems is too low for a messaging broker (eg. 1024 on several Linux distributions). We recommend allowing for at least 65536 file descriptors for user rabbitmq in production environments. 4096 should be sufficient for most development workloads.

There are two limits in play: the maximum number of open files the OS kernel allows (fs.file-max on Linux, kern.maxfilesperproc on OS X and FreeBSD) and the per-user limit (ulimit -n). The former must be higher than the latter.

For more information about controlling the system-wide limit, please refer to the excellent Riak guide on open file limit tuning.

Verifying the Limit

RabbitMQ management UI displays the number of file descriptors available for it to use on the Overview tab.

rabbitmqctl status
includes the same value.

The following command

ulimit -a
can be used to display effective limits for the current user. There may be more convenient OS-specific ways of doing that for a running process, such as the /proc filesystem on Linux.

Configuration Management Tools

Configuration management tools (e.g. Chef, Puppet, BOSH) provide assistance with system limit tuning. Our developer tools guide lists relevant modules and projects.

Getting Help and Providing Feedback

If you have questions about the contents of this guide or any other topic related to RabbitMQ, don't hesitate to ask them on the RabbitMQ mailing list.

Help Us Improve the Docs <3

If you'd like to contribute an improvement to the site, its source is available on GitHub. Simply fork the repository and submit a pull request. Thank you!