RabbitMQ - Configuration

RabbitMQ comes with default built-in settings which will most likely be sufficient for running your RabbitMQ server effectively. If it runs fine, then you probably don't need any configuration at all. If you have other constraints, RabbitMQ provides two general ways to customise the server:

environment variables define ports, file locations, names;
a configuration file defines component settings for permissions, limits and clusters, and also for plugins.

RabbitMQ environment settings are prefixed with RABBITMQ_ and environment settings take priority over start script built-in default values. Local shell environment settings will take priority over the more general settings described below. Similarly, values set in the configuration file take priority over built-in defaults.

Verify Configuration

The active configuration can be verified in the startup banner, e.g. the active configuration file:

config file(s) : /etc/rabbitmq/rabbitmq.config

This may appear in on the console or in a file, depending on how the broker was started:

Linux (when running as a service): see the startup_log file in the log directory;
MacOSX (macports): see ${install prefix}/var/log/rabbitmq/startupitem.log;
Started as rabbitmq-server (without the -detached option): see console output;
Windows Service: enable RABBITMQ_CONSOLE_LOG and check the .debug file.

The startup banner is not available if the broker is started in detached mode.

Customise RabbitMQ Environment

Unix (general)

On Unix-based systems (including Linux, MacOSX) you can create/edit rabbitmq-env.conf to define environment variables. Its location is not configurable (unlike rabbitmq.config, which is by default in the same directory).

Use the standard environment variable names (but drop the RABBITMQ_ prefix) e.g.

#example rabbitmq-env.conf file entries
#Rename the node
NODENAME=bunny
#Config file location and new filename bunnies.config
CONFIG_FILE=/etc/rabbitmq/testdir/bunnies

More info on using rabbitmq-env.conf

Windows

If you need to customise names, ports, locations, it is easiest to configure environment variables in the Windows dialogue: Start > Settings > Control Panel > System > Advanced > Environment Variables.

Create or edit the system variable name and value. For environment changes to take effect, open a new Command Prompt, then restart the broker or re-install the service.

RabbitMQ Environment Variables

It is unlikely you will need to set any of these environment variables. If you have non standard requirements, then RabbitMQ environment variables include:

Name	Default	Description
RABBITMQ_NODE_IP_ADDRESS		Defaults to the empty string - meaning bind to all network interfaces. This can be changed if you only want to bind to one network interface.
RABBITMQ_NODE_PORT	5672
HOSTNAME	Unix, Linux: `env hostname` MacOSX: `env hostname -s`	The name of the current machine
COMPUTERNAME	Windows: localhost	The name of the current machine
RABBITMQ_BASE	Windows: %APPDATA%\RabbitMQ	This base directory contains sub-directories for the RabbitMQ server's database and log files. Alternatively, set RABBITMQ_MNESIA_BASE and RABBITMQ_LOG_BASE individually.
RABBITMQ_NODENAME	*Unix: rabbit@$HOSTNAME Windows:** rabbit@%COMPUTERNAME%	The node name should be unique per erlang-node-and-machine combination. To run multiple nodes, see the clustering guide.
RABBITMQ_CONFIG_FILE	*Unix: /etc/rabbitmq/rabbitmq Windows:** %RABBITMQ_BASE%\rabbitmq	If the configuration file is present it is used by the server to configure RabbitMQ components. The .config extension is automatically appended by the Erlang runtime. This file is also used to auto-configure RabbitMQ clusters.
RABBITMQ_MNESIA_BASE	*Unix: /var/lib/rabbitmq/mnesia Windows:** %RABBITMQ_BASE%\db	The directory where Mnesia database files should be placed.
RABBITMQ_LOG_BASE	*Unix: /var/log/rabbitmq Windows:** %RABBITMQ_BASE%\log	Log files generated by the server will be placed in this directory.
RABBITMQ_PLUGINS_DIR		The plugins will be found in this directory.
RABBITMQ_ENABLED_PLUGINS_FILE	*Unix: /etc/rabbitmq/enabled_plugins Windows:** %RABBITMQ_BASE%\enabled_plugins	This file records explicitly enabled plugins.
ERLANG_SERVICE_MANAGER_PATH	Windows Service: %ERLANG_HOME%\erts-`x.x.x`\bin	This path is the location of erlsrv.exe, the Erlang service wrapper script.
RABBITMQ_SERVICENAME	Windows Service: RabbitMQ	The name of the installed service. This will appear in services.msc.
RABBITMQ_CONSOLE_LOG	Windows Service:	Set this variable to new or reuse to redirect console output from the server to a file named %RABBITMQ_SERVICENAME%.debug in the default RABBITMQ_BASE directory. If not set, console output from the server will be discarded (default). new A new file will be created each time the service starts. reuse The file will be overwritten each time the service starts.

* Unix, Linux, MacOSX

Paths are given relative to the installation directory prefix. For example Mac OSX (macports) are normally based in /opt/local/, or /usr/local on Mac OSX (homebrew) and some BSD installations.

Configuration File

The rabbitmq.config File

The configuration file rabbitmq.config allows the RabbitMQ core application, Erlang services and RabbitMQ plugins to be configured. It is a standard Erlang configuration file, documented on the Erlang Config Man Page.

An example configuration file follows:

  [
    {mnesia, [{dump_log_write_threshold, 1000}]},
    {rabbit, [{tcp_listeners, [5673]}]}
  ].

This example will alter the dump_log_write_threshold for mnesia (increasing from the default of 100), and alter the port RabbitMQ listens on from 5672 to 5673.

This configuration file is not the same as rabbitmq-env.conf, which can be used to set environment variables on non-windows systems. A future release of RabbitMQ will unify the two configuration mechanisms.

Location of rabbitmq.config and rabbitmq-env.conf

The location of these files is distribution-specific. By default, they are not created, but expect to be located in the following places on each platform:

Generic UNIX - /etc/rabbitmq/
Debian - /etc/rabbitmq/
RPM - /etc/rabbitmq/
Mac OS X (Macports) - /opt/local/etc/rabbitmq/
Windows - %APPDATA%\RabbitMQ\

If rabbitmq-env.conf doesn't exist, it can be created manually in the default location only. It is not used on Windows systems.

If rabbitmq.config doesn't exist, it can be created manually. Set the RABBITMQ_CONFIG_FILE environment variable if you change the location. The Erlang runtime automatically appends the .config extension to the value of this variable.

Restart the server after changes. Windows service users need to take additional steps when changing plugins.

Variables Configurable in rabbitmq.config

Many users of RabbitMQ never need to change any of these values, and some are fairly obscure. However, for completeness they are all listed here.

Key	Default value	Documentation
tcp_listeners	[5672]	List of ports on which to listen for AMQP connections (without SSL). Can contain integers (meaning "listen on all interfaces") or tuples such as {"127.0.0.1", 5672} to listen on a single interface.
ssl_listeners	[]	As above, for SSL connections.
ssl_options	[]	SSL configuration. See the SSL documentation.
vm_memory_high_watermark	0.4	Memory threshold at which the flow control is triggered. See the memory-based flow control documentation.
frame_max	131072	Maximum permissible size of a frame (in bytes) to negotiate with clients. Setting to 0 means "unlimited" but will trigger a bug in some QPid clients. Setting a larger value may improve throughput; setting a smaller value may improve latency.
default_vhost	<<"/">>	Virtual host to create when RabbitMQ creates a new database from scratch. The exchange amq.rabbitmq.log will exist in this virtual host.
default_user	<<"guest">>	User name to create when RabbitMQ creates a new database from scratch.
default_pass	<<"guest">>	Password for the default user.
default_user_tags	[administrator]	Tags for the default user.
default_permissions	[<<".">>, <<".">>, <<".*">>]	Permissions to assign to the default user when creating it.
cluster_nodes	[]	Set this to cause clustering to happen automatically.
server_properties	[]	List of key-value pairs to announce to clients on connection.
collect_statistics	none	Statistics collection mode. Primarily relevant for the management plugin. Options are: none (do not emit statistics events) coarse (emit per-queue / per-channel / per-connection statistics) fine (also emit per-message statistics) You probably don't want to change this yourself.
collect_statistics_interval	5000	Statistics collection interval in milliseconds. Primarily relevant for the management plugin.
auth_mechanisms	['PLAIN', 'AMQPLAIN']	SASL authentication mechanisms to offer to clients.
auth_backends	[rabbit_auth_backend_internal]	List of authentication databases to use. Other databases than rabbit_auth_backend_internal are available through plugins.
delegate_count	16	Number of delegate processes to use for intra-cluster communication. On a machine which has a very large number of cores and is also part of a cluster, you may wish to increase this value.
trace_vhosts	[]	Used internally by the tracer. You shouldn't change this.
tcp_listen_options	[binary, {packet, raw}, {reuseaddr, true}, {backlog, 128}, {nodelay, true}, {exit_on_close, false}]	Default socket options. You probably don't want to change this.
hipe_compile	false	Set to true to precompile parts of RabbitMQ with the High Performance Erlang compiler. This will increase the message rate that the server can handle, while also increasing startup time. You might see 20-50% better performance at the cost of approximately 1 minute delay at startup. These figures are highly workload- and hardware-dependent. HiPE support may not be compiled into your Erlang installation. If it is not, enabling this option will just cause a warning message to be displayed and startup will proceed as normal. For example, Debian / Ubuntu users will need to install the erlang-base-hipe package. HiPE is not available at all on some platforms, notably including Windows. This option should be considered experimental. If your Erlang VM segfaults, disable this option again.
msg_store_index_module	rabbit_msg_store_ets_index	Implementation module for queue indexing. You probably don't want to change this.
backing_queue_module	rabbit_variable_queue	Implementation module for queue contents. You probably don't want to change this.
msg_store_file_size_limit	16777216	Tunable value for the persister. You almost certainly should not change this.
queue_index_max_journal_entries	262144	Tunable value for the persister. You almost certainly should not change this.

In addition, many plugins can have sections in the configuration file, with names of the form rabbitmq_plugin. Our maintained plugins are documented in the following locations:

Configuration