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 three general ways to customise the server:

environment variables
define ports, file locations and names (taken from the shell, or set in the rabbitmq-env.conf file)
a configuration file
defines server component settings for permissions, limits and clusters, and also plugin settings.
runtime parameters and policies
defines cluster-wide settings which can change at run time

Verify Configuration

The active configuration can be verified in the broker log, e.g. the active configuration file:

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

will show up in the log file.

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).

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

#example rabbitmq-env.conf file entries
#Rename the node
NODENAME=bunny@myhost
#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 on Windows, the service must be re-installed. It is not sufficient to restart the service.

RabbitMQ Environment Variables

RabbitMQ environment variable names have the prefix RABBITMQ_. A typical variable called RABBITMQ_var_name is set as follows:

  • a shell environment variable called RABBITMQ_var_name is used if this is defined;
  • otherwise, a variable called var_name is used if this is set in the rabbitmq-env.conf file;
  • otherwise, a system-specified default value is used.

In this way, variables set in the shell environment take priority over variables set in rabbitmq-env.conf, which in turn over-ride RabbitMQ built-in defaults.

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

NameDefaultDescription
RABBITMQ_NODE_IP_ADDRESS the empty string - meaning bind to all network interfaces. Change this if you only want to bind to one network interface.
RABBITMQ_NODE_PORT 5672
RABBITMQ_DIST_PORT RABBITMQ_NODE_PORT + 20000 Port to use for clustering. Ignored if your config file sets inet_dist_listen_min or inet_dist_listen_max
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_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.
RABBITMQ_CTL_ERL_ARGS None Parameters for the erl command used when invoking rabbitmqctl. This should be overridden for debugging purposes only.
RABBITMQ_SERVER_ERL_ARGS
  • Unix*: "+K true +A30 +P 1048576 -kernel inet_default_connect_options [{nodelay,true}]"
  • Windows: None
Standard parameters for the erl command used when invoking the RabbitMQ Server. This should be overridden for debugging purposes only. Overriding this variable replaces the default value.
RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS
  • Unix*: None
  • Windows: None
Additional parameters for the erl command used when invoking the RabbitMQ Server. The value of this variable is appended the default list of arguments (RABBITMQ_SERVER_ERL_ARGS).
RABBITMQ_SERVER_START_ARGS None Extra parameters for the erl command used when invoking the RabbitMQ Server. This will not override RABBITMQ_SERVER_ERL_ARGS.
* Unix, Linux, MacOSX

In addition, there are several environment variables which tell RabbitMQ where to locate its database, log files, plugins, configuration etc.

Other variables upon which RabbitMQ depends are:

NameDefaultDescription
HOSTNAME
  • Unix, Linux: `env hostname`
  • MacOSX: `env hostname -s`
The name of the current machine
COMPUTERNAME Windows: localhost The name of the current machine
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.

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.

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 - $RABBITMQ_HOME/etc/rabbitmq/
  • Debian - /etc/rabbitmq/
  • RPM - /etc/rabbitmq/
  • Mac OS X (Macports) - ${install_prefix}/etc/rabbitmq/, the Macports prefix is usually /opt/local
  • 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 will need to re-install the service after adding or removing a configuration file.

Example rabbitmq.config file

We ship an example configuration file with the RabbitMQ server, named rabbitmq.config.example. This example file contains an example of most of the configuration items you might want to set (with some very obscure ones omitted) along with documentation for those settings. All configuration items are commented out in the example, so you can uncomment what you need.

In most distributions we place this example file in the same location as the real file should be placed (see above). However, for the Debian and RPM distributions policy forbids doing so; instead you can find it in /usr/share/doc/rabbitmq-server/ or /usr/share/doc/rabbitmq-server-3.3.4/ respectively.

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 Documentation
tcp_listeners 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.

Default: [5672]

handshake_timeout Maximum time for AMQP 0-8/0-9/0-9-1 handshake (after socket connection and SSL handshake), in milliseconds.

Default: 10000

ssl_listeners As above, for SSL connections.

Default: []

ssl_options SSL configuration. See the SSL documentation.

Default: []

ssl_handshake_timeout SSL handshake timeout, in milliseconds.

Default: 5000

vm_memory_high_watermark Memory threshold at which the flow control is triggered. See the memory-based flow control documentation.

Default: 0.4

vm_memory_high_watermark_paging_ratio Fraction of the high watermark limit at which queues start to page messages out to disc to free up memory. See the memory-based flow control documentation.

Default: 0.5

disk_free_limit Disk free space limit of the partition on which RabbitMQ is storing data. When available disk space falls below this limit, flow control is triggered. The value may be set relative to the total amount of RAM (e.g. {mem_relative, 1.0}). The value may also be set to an integer number of bytes. By default free disk space must exceed 50MB. See the memory-based flow control documentation.

Default: 50000000

log_levels Controls the granularity of logging. The value is a list of log event category and log level pairs.

The level can be one of 'none' (no events are logged), 'error' (only errors are logged), 'warning' (only errors and warning are logged), or 'info' (errors, warnings and informational messages are logged).

At present there are three categories defined. Other, currently uncategorised, events are always logged.

The categories are:

  • connection - for all events relating to network connections
  • mirroring - for all events relating to mirrored queues
  • federation - for all events relating to federation

Default: [{connection, info}]

frame_max 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: 131072

channel_max Maximum permissible number of channels to negotiate with clients. Setting to 0 means "unlimited". Using more channels increases memory footprint of the broker.

Default: 0

heartbeat Value representing the heartbeat delay, in seconds, that the server sends in the connection.tune frame. If set to 0, heartbeats are disabled. Clients might not follow the server suggestion, see the AMQP reference for more details. Disabling heartbeats might improve performance in situations with a great number of connections, but might lead to connections dropping in the presence of network devices that close inactive connections.

Default: 580

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: <<"/">>

default_user User name to create when RabbitMQ creates a new database from scratch.

Default: <<"guest">>

default_pass Password for the default user.

Default: <<"guest">>

default_user_tags Tags for the default user.

Default: [administrator]

default_permissions Permissions to assign to the default user when creating it.

Default: [<<".*">>, <<".*">>, <<".*">>]

loopback_users List of users which are only permitted to connect to the broker via a loopback interface (i.e. localhost).

If you wish to allow the default guest user to connect remotely, you need to change this to [].

Default: [<<"guest">>]

cluster_nodes Set this to cause clustering to happen automatically when a node starts for the very first time. The first element of the tuple is the nodes that the node will try to cluster to. The second element is either disc or ram and determines the node type.

Default: {[], disc}

server_properties List of key-value pairs to announce to clients on connection.

Default: []

collect_statistics 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.

Default: none

collect_statistics_interval Statistics collection interval in milliseconds. Primarily relevant for the management plugin.

Default: 5000

auth_mechanisms SASL authentication mechanisms to offer to clients.

Default: ['PLAIN', 'AMQPLAIN']

auth_backends

List of authentication / authorisation databases to use. This list can contain names of modules (in which case the same module is used for both authentication and authorisation), or 2-tuples like {ModN, ModZ} in which case ModN is used for authentication and ModZ is used for authorisation.

Other databases than rabbit_auth_backend_internal are available through plugins.

Default: [rabbit_auth_backend_internal]

reverse_dns_lookups Set to true to have RabbitMQ perform a reverse DNS lookup on client connections, and present that information through rabbitmqctl and the management plugin.

Default: false

delegate_count 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.

Default: 16

trace_vhosts Used internally by the tracer. You shouldn't change this.

Default: []

tcp_listen_options Default socket options. You probably don't want to change this.

Default:

[binary, {packet,        raw},
         {reuseaddr,     true},
         {backlog,       128},
         {nodelay,       true},
         {exit_on_close, false}]

hipe_compile 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.

Default: false

cluster_partition_handling How to handle network partitions. One of ignore, pause_minority or autoheal. See the documentation on partitions for more information.

Default: ignore

msg_store_index_module Implementation module for queue indexing. You probably don't want to change this.

Default: rabbit_msg_store_ets_index

backing_queue_module Implementation module for queue contents. You probably don't want to change this.

Default: rabbit_variable_queue

msg_store_file_size_limit Tunable value for the persister. You almost certainly should not change this.

Default: 16777216

mnesia_table_loading_timeout Timeout used when waiting for Mnesia tables in a cluster to become available.

Default: 30000

queue_index_max_ journal_entries Tunable value for the persister. You almost certainly should not change this.

Default: 65536

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: