Menu

Configuration

Overview

RabbitMQ comes with default built-in settings. Those can be entirely sufficient in some environment (e.g. development and QA). For all other cases, as well as production deployment tuning, there is a way to configure many things in the broker as well as plugins.

This guide covers a number of topics related to configuration:

and more.

Since configuration affects many areas of the system, including plugins, individual documentation guides dive deeper into what can be configured. Runtime Tuning is a companion to this guide that focuses on the configurable parameters in the runtime. Production Checklist is a related guide that outlines what settings will likely need tuning in most production environments.

Means of Configuration

A RabbitMQ node can be configured using a number of mechanisms responsible for different areas:

Mechanism Description
Configuration File(s) defines server and plugin settings for and so on.
Environment Variables define node name, file and directory locations, runtime flags taken from the shell, or set in the environment configuration file, rabbitmq-env.conf (Linux, MacOS, BSD) and rabbitmq-env-conf.bat (Windows)
rabbitmqctl When internal authentication/authorization backend is used, rabbitmqctl is the tool that manages virtual hosts, users and permissions.
rabbitmq-plugins rabbitmq-plugins is the tool that manages enabled plugins.
Parameters and Policies defines cluster-wide settings which can change at run time as well as settings that are convenient to configure for groups of queues (exchanges, etc) such as including optional queue arguments.
Runtime (Erlang VM) Flags Control lower-level aspects of the system: memory allocation settings, inter-node communication buffer size, runtime scheduler settings and more.
Operating System Kernel Limits Control process limits enforced by the kernel: max open file handle limit, max number of processes and kernel threads, max resident set size and so on.

Most settings are configured using the first two methods. This guide, therefore, focuses on them.

Configuration File(s)

Introduction

While some settings in RabbitMQ can be tuned using environment variables, most are configured using a configuration file, usually named rabbitmq.conf. This includes configuration for the core server as well as plugins. The sections below cover the syntax, location, how to configure things to which the format isn't well-suited, where to find examples, and so on.

Prior to RabbitMQ 3.7.0, RabbitMQ config file was named rabbitmq.config and used an Erlang term configuration format. That format is still supported for backwards compatibility. Those running 3.7.0 or later are recommended to consider the new sysctl format.

Config File Locations

Default config file locations vary between operating systems and package types.

This topic is covered in more detail in the rest of this guide.

When in doubt about RabbitMQ config file location for your OS and installation method, consult the log file and/or management UI as explained in the following sections.

Verify Configuration: How to Find Config File Location

The active configuration file can be verified by inspecting the RabbitMQ log file. It will show up in the log file at the top, along with the other broker boot log entries. For example:

node           : rabbit@example
home dir       : /var/lib/rabbitmq
config file(s) : /etc/rabbitmq/advanced.config
               : /etc/rabbitmq/rabbitmq.conf

If the configuration file cannot be found or read by RabbitMQ, the log entry will say so:

node           : rabbit@example
home dir       : /var/lib/rabbitmq
config file(s) : /var/lib/rabbitmq/hare.conf (not found)

Alternatively config file location can be found in the management UI, together with other details about nodes.

When troubleshooting configuration settings, it is very useful to verify that the config file path is correct, exists and can be loaded (e.g. the file is readable) before checking effective node configuration.

Verify Configuration: How to Check Effective Configuration

It is possible to print effective configuration (user provided values merged into defaults) using the rabbitmqctl environment command. It will print applied configuration for every application (RabbitMQ, plugins, libraries) running on the node.

Effective configuration should be verified together with config file location (see above). It is a useful step in troubleshooting a broad range of problems.

The New and Old Config File Formats

Prior to RabbitMQ 3.7.0, RabbitMQ config file was named rabbitmq.config and used an Erlang term configuration format. That format is still supported for backwards compatibility. Those running 3.7.0 or later are recommended to consider the new sysctl format.

The new format is easier to generate deployment automation tools. Compare

ssl_options.cacertfile           = /path/to/ca_certificate.pem
ssl_options.certfile             = /path/to/server_certificate.pem
ssl_options.keyfile              = /path/to/server_key.pem
ssl_options.verify               = verify_peer
ssl_options.fail_if_no_peer_cert = true

with

[
  {rabbit, [{ssl_options, [{cacertfile,           "/path/to/ca_certificate.pem"},
                           {certfile,             "/path/to/server_certificate.pem"},
                           {keyfile,              "/path/to/server_key.pem"},
                           {verify,               verify_peer},
                           {fail_if_no_peer_cert, true}]}]}
].

While the new config format is more convenient for humans to edit and machines to generate, it is also relatively limited compared to the classic config format used prior to RabbitMQ 3.7.0. For example, when configuring LDAP support, it may be necessary to use deeply nested data structures to express desired configuration. To accommodate this need, RabbitMQ still supports the classic rabbitmq.config config files as well as ability to use both formats at the same time (advanced.config). This is covered in more detail in the following sections.

The rabbitmq.conf File

The configuration file rabbitmq.conf allows the RabbitMQ server and plugins to be configured. Starting with RabbitMQ 3.7.0, the format is in the sysctl format.

The syntax can be briefly explained in 3 lines:

  • One setting uses one line
  • Lines are structured Key = Value
  • Any line starting with a # character is a comment

A minimalistic example configuration file follows:

# this is a comment
listeners.tcp.default = 5673

The same example in the classic config format:

[
  {rabbit, [
      {tcp_listeners, [5673]}
    ]
  }
].

This example will alter the port RabbitMQ listens on for AMQP 0-9-1 and AMQP 1.0 client connections from 5672 to 5673.

The RabbitMQ server source repository contains an example rabbitmq.conf file named rabbitmq.conf.example. It contains examples of most of the configuration items you might want to set (with some very obscure ones omitted), along with documentation for those settings.

Documentation guides such as Networking, TLS, or Access Control will often provide examples in both formats.

Note that this configuration file is not to be confused with the environment variable configuration files, rabbitmq-env.conf and rabbitmq-env-conf.bat.

To override the main RabbitMQ config file location, use the RABBITMQ_CONFIG_FILE environment variable. Use .conf as file extension for the new style config format.

The advanced.config File

Some configuration settings are not possible or are difficult to configure using the sysctl format. As such, it is possible to use an additional config file in the Erlang term format (same as rabbitmq.config). That file is commonly named advanced.config. It will be merged with the configuration provided in rabbitmq.conf.

The RabbitMQ server source repository contains an example advanced.config file named advanced.config.example. It focuses on the options that are typically set using the advanced config.

To override the advanced config file location, use the RABBITMQ_ADVANCED_CONFIG_FILE environment variable.

The rabbitmq.config (Classic Format) File

RabbitMQ 3.7.0 and later versions still support the classic configuration file format, known as rabbitmq.config. To use it, export RABBITMQ_CONFIG_FILE to point to the file with a .config extension to indicate that RabbitMQ should treat it as a classic config format.

The RabbitMQ server source repository contains an example configuration file named rabbitmq.config.example. It contains an example of most of the configuration items in the classic config format.

To override the main RabbitMQ config file location, use the RABBITMQ_CONFIG_FILE environment variable. Use .config as file extension for the classic config format.

The use of classic config format should only be limited to the advanced.config file and settings that cannot be configured using the ini-style config file.

Location of rabbitmq.conf 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 (Homebrew): ${install_prefix}/etc/rabbitmq/, the Homebrew cellar prefix is usually /usr/local
  • Windows: %APPDATA%\RabbitMQ\

If rabbitmq-env.conf doesn't exist, it can be created manually in the location, specified by the RABBITMQ_CONF_ENV_FILE variable. On Windows systems, it is named rabbitmq-env-conf.bat.

If rabbitmq.conf doesn't exist, it can be created manually. Set the RABBITMQ_CONFIG_FILE environment variable if you change the location. RabbitMQ automatically appends the .conf 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.conf File

The RabbitMQ server source repository contains examples for the configuration files:

These files contain examples 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. Note that the example files are meant to be used as, well, examples, and should not be treated as a general recommendation.

In most distributions the example file is placed into the same location as the real file should be placed (see above). On Debian and RPM distributions policy forbids doing so; instead find the file under /usr/share/doc/rabbitmq-server/ or /usr/share/doc/rabbitmq-server-3.7.16/, respectively.

Core Server Variables Configurable in rabbitmq.conf

These variables are the most common. The list is not complete, as some settings are quite obscure.

Key Documentation
listeners Ports or hostname/pair on which to listen for "plain" AMQP 0-9-1 and AMQP 1.0 connections (without TLS). See the Networking guide for more details and examples.

Default:

listeners.tcp.default = 5672

num_acceptors.tcp Number of Erlang processes that will accept connections for the TCP listeners.

Default:

num_acceptors.tcp = 10

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

Default:

handshake_timeout = 10000

listeners.ssl Ports or hostname/pair on which to listen for TLS-enabled AMQP 0-9-1 and AMQP 1.0 connections. See the TLS guide for more details and examples.

Default: none (not set)

num_acceptors.ssl Number of Erlang processes that will accept TLS connections from clients.

Default:

num_acceptors.ssl = 10

ssl_options TLS configuration. See the TLS support documentation.

Default:

ssl_options = none

ssl_handshake_timeout TLS handshake timeout, in milliseconds.

Default:

ssl_handshake_timeout = 5000

vm_memory_high_watermark Memory threshold at which the flow control is triggered. Can be absolute or relative to the amount of RAM available to the OS:
vm_memory_high_watermark.relative = 0.6
vm_memory_high_watermark.absolute = 2GB
See the memory-based flow control and alarms documentation.

Default:

vm_memory_high_watermark.relative = 0.4

vm_memory_calculation_strategy Strategy for memory usage reporting. Can be one of the following:
  • allocated: uses Erlang memory allocator statistics
  • rss: uses operating system RSS memory reporting. This uses OS-specific means and may start short lived child processes.
  • legacy: uses legacy memory reporting (how much memory is considered to be used by the runtime). This strategy is fairly inaccurate.
  • erlang: same as legacy, preserved for backwards compatibility

Default:

vm_memory_calculation_strategy = allocated

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:

vm_memory_high_watermark_paging_ratio = 0.5

total_memory_available_override_value Makes it possible to override the total amount of memory available, as opposed to inferring it from the environment using OS-specific means. This should only be used when actual maximum amount of RAM available to the node doesn't match the value that will be inferred by the node, e.g. due to containerization or similar constraints the node cannot be aware of. The value may be set to an integer number of bytes or, alternatively, in information units (e.g `8GB`). For example, when the value is set to 4 GB, the node will believe it is running on a machine with 4 GB of RAM.

Default: `undefined` (not set or used).

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 can be set relative to the total amount of RAM or as an absolute value in bytes or, alternatively, in information units (e.g `50MB` or `5GB`):
disk_free_limit.relative = 3.0
disk_free_limit.absolute = 2GB
By default free disk space must exceed 50MB. See the Disk Alarms documentation.

Default:

disk_free_limit.absolute = 50MB

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

The level can be one of error (only errors are logged), warning (only errors and warning are logged), info (errors, warnings and informational messages are logged), or debug (errors, warnings, informational messages and debugging m essages are logged).

Default:

log.file.level = info

channel_max Maximum permissible number of channels to negotiate with clients, not including a special channel number 0 used in the protocol. Setting to 0 means "unlimited", a dangerous value since applications sometimes have channel leaks. Using more channels increases memory footprint of the broker.

Default:

channel_max = 2047

channel_operation_timeout Channel operation timeout in milliseconds (used internally, not directly exposed to clients due to messaging protocol differences and limitations).

Default:

channel_operation_timeout = 15000

heartbeat Value representing the heartbeat timeout suggested by the server during connection parameter negotiation. If set to 0 on both ends, heartbeats are disabled (this is not recommended). See the Heartbeats guide for details.

Default:

heartbeat = 60

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_vhost = /

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

Default:

default_user = guest

default_pass Password for the default user.

Default:

default_pass = guest

default_user_tags Tags for the default user.

Default:

default_user_tags.administrator = true

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

Default:

default_permissions.configure = .*
default_permissions.read = .*
default_permissions.write = .*

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

To allow the default `guest` user to connect remotely (a security practice unsuitable for production use), set this to `none`:

# awful security practice,
# consider creating a new
# user with secure generated credentials!
loopback_users = none

To restrict another user to localhost-only connections, do it like so (`monitoring` is the name of the user):

loopback_users.monitoring = true

Default:

# guest uses well known
# credentials and can only
# log in from localhost
# by default
loopback_users.guest = true

cluster_formation.classic_config.nodes Classic peer discovery backend's list of nodes to contact. For example, to cluster with nodes `rabbit@hostname1` and `rabbit@hostname2` on first boot:
cluster_formation.classic_config.nodes.1 = rabbit@hostname1
cluster_formation.classic_config.nodes.2 = rabbit@hostname2

Default: `none` (not set)

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)

Default:

collect_statistics = none

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

Default:

collect_statistics_interval = 5000

management_db_cache_multiplier Affects the amount of time the management plugin will cache expensive management queries such as queue listings. The cache will multiply the elapsed time of the last query by this value and cache the result for this amount of time.

Default:

management_db_cache_multiplier = 5

auth_mechanisms SASL authentication mechanisms to offer to clients.

Default:

auth_mechanisms.1 = PLAIN
auth_mechanisms.2 = AMQPLAIN

auth_backends

List of authentication and authorisation backends to use. See the access control guide for details and examples.

Other databases than `rabbit_auth_backend_internal` are available through plugins.

Default:

auth_backends.1 = 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:

reverse_dns_lookups = 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:

delegate_count = 16

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

Default:

tcp_listen_options.backlog = 128
tcp_listen_options.nodelay = true
tcp_listen_options.linger.on = true
tcp_listen_options.linger.timeout = 0
tcp_listen_options.exit_on_close = false

hipe_compile

Set to `true` to precompile parts of RabbitMQ with HiPE, a just-in-time compiler for Erlang.

Enabling HiPE can improve throughput by double digit % at the cost of a few minutes delay at startup. These figures are highly workload- and hardware-dependent.

The startup penalty can be avoided via precompilation. See rabbitmqctl hipe_compile and `RABBITMQ_SERVER_CODE_PATH` environment variable documentation.

Erlang installations must be compiled with HiPE support. If it is not, enabling this option will have no effect. Debian and Ubuntu provide both a HiPE-enabled base Erlang package (erlang-base-hipe) and a regular one (erlang-base).

HiPE is not supported on Windows.

Default:

hipe_compile = false

cluster_partition_handling How to handle network partitions. Available modes are:
  • ignore
  • autoheal
  • pause_minority
  • pause_if_all_down
pause_if_all_down mode requires additional parameters:
  • nodes
  • recover
See the documentation on partitions for more information.

Default:

cluster_partition_handling = ignore

cluster_keepalive_interval How frequently nodes should send keepalive messages to other nodes (in milliseconds). Note that this is not the same thing as net_ticktime; missed keepalive messages will not cause nodes to be considered down.

Default:

cluster_keepalive_interval = 10000

queue_index_embed_msgs_below Size in bytes of message below which messages will be embedded directly in the queue index. You are advised to read the persister tuning documentation before changing this.

Default:

queue_index_embed_msgs_below = 4096

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

Default:

mnesia_table_loading_retry_timeout = 30000

mnesia_table_loading_retry_limit Retries when waiting for Mnesia tables in the cluster startup. Note that this setting is not applied to Mnesia upgrades or node deletions.

Default:

mnesia_table_loading_retry_limit = 10

mirroring_sync_batch_size Batch size used to transfer messages to an unsynchronised replica (queue mirror). See documentation on eager batch synchronization.

Default:

mirroring_sync_batch_size = 4096

queue_master_locator Queue master location strategy. Available strategies are:
  • min-masters
  • client-local
  • random
See the documentation on queue master location for more information.

Default:

queue_master_locator = client-local

proxy_protocol If set to true, RabbitMQ will expect a proxy protocol header to be sent first when an AMQP connection is opened. This implies to set up a proxy protocol-compliant reverse proxy (e.g. HAproxy or AWS ELB) in front of RabbitMQ. Clients can't directly connect to RabbitMQ when proxy protocol is enabled, so all connections must go through the reverse proxy.

See the networking guide for more information.

Default:

proxy_protocol = false

The following configuration settings can be set in the advanced config file only, under the rabbit section.

Key Documentation
msg_store_index_module Implementation module for queue indexing. You are advised to read the message store tuning documentation before changing this.

Default: rabbit_msg_store_ets_index

{rabbit, [
{msg_store_index_module, rabbit_msg_store_ets_index}
]}

backing_queue_module Implementation module for queue contents.

Default:

{rabbit, [
{backing_queue_module, rabbit_variable_queue}
]}

msg_store_file_size_limit Message store segment file size. Changing this for a node with an existing (initialised) database is dangerous can lead to data loss!

Default: 16777216

{rabbit, [
%% Changing this for a node
%% with an existing (initialised) database is dangerous can
%% lead to data loss!
{msg_store_file_size_limit, 16777216}
]}

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

Default:

{rabbit, [
{trace_vhosts, []}
]}

msg_store_credit_disc_bound The credits that a queue process is given by the message store.

By default, a queue process is given 4000 message store credits, and then 800 for every 800 messages that it processes.

Messages which need to be paged out due to memory pressure will also use this credit.

The Message Store is the last component in the credit flow chain. Learn about credit flow.

This value only takes effect when messages are persisted to the message store. If messages are embedded on the queue index, then modifying this setting has no effect because credit_flow is NOT used when writing to the queue index.

Default:

{rabbit, [
{msg_store_credit_disc_bound, {4000, 800}}
]}

queue_index_max_journal_entries After how many queue index journal entries it will be flushed to disk.

Default:

{rabbit, [
{queue_index_max_journal_entries, 32768}
]}

lazy_queue_explicit_gc_run_operation_threshold Tunable value only for lazy queues when under memory pressure. This is the threshold at which the garbage collector and other memory reduction activities are triggered. A low value could reduce performance, and a high one can improve performance, but cause higher memory consumption. You almost certainly should not change this.

Default:

{rabbit, [
{lazy_queue_explicit_gc_run_operation_threshold, 1000}
]}

queue_explicit_gc_run_operation_threshold Tunable value only for normal queues when under memory pressure. This is the threshold at which the garbage collector and other memory reduction activities are triggered. A low value could reduce performance, and a high one can improve performance, but cause higher memory consumption. You almost certainly should not change this.

Default:

{rabbit, [
{queue_explicit_gc_run_operation_threshold, 1000}
]}

Several plugins that ship with RabbitMQ have dedicated documentation guides that cover plugin configuration:

Configuration Value Encryption

Sensitive configuration entries (e.g. password, URL containing credentials) can be encrypted in the RabbitMQ configuration file. The broker decrypts encrypted entries on start.

Note that encrypted configuration entries don't make the system meaningfully more secure. Nevertheless, they allow deployments of RabbitMQ to conform to regulations in various countries requiring that no sensitive data should appear in plain text in configuration files.

Encrypted values must be inside an Erlang encrypted tuple: {encrypted, ...}. Here is an example of a configuration file with an encrypted password for the default user:

[
  {rabbit, [
      {default_user, <<"guest">>},
      {default_pass,
        {encrypted,
         <<"cPAymwqmMnbPXXRVqVzpxJdrS8mHEKuo2V+3vt1u/fymexD9oztQ2G/oJ4PAaSb2c5N/hRJ2aqP/X0VAfx8xOQ==">>
        }
      },
      {config_entry_decoder, [
             {passphrase, <<"mypassphrase">>}
         ]}
    ]}
].

Note the config_entry_decoder key with the passphrase that RabbitMQ will use to decrypt encrypted values.

The passphrase doesn't have to be hardcoded in the configuration file, it can be in a separate file:

[
  {rabbit, [
      %% ...
      {config_entry_decoder, [
             {passphrase, {file, "/path/to/passphrase/file"}}
         ]}
    ]}
].

RabbitMQ can also request an operator to enter the passphrase when it starts by using {passphrase, prompt}.

Use rabbitmqctl and the encode command to encrypt values:

rabbitmqctl encode '<<"guest">>' mypassphrase
{encrypted,<<"... long encrypted value...">>}
rabbitmqctl encode '"amqp://fred:secret@host1.domain/my_vhost"' mypassphrase
{encrypted,<<"... long encrypted value...">>}

Add the decode command if you want to decrypt values:

rabbitmqctl decode '{encrypted, <<"...">>}' mypassphrase
<<"guest">>
rabbitmqctl decode '{encrypted, <<"...">>}' mypassphrase
"amqp://fred:secret@host1.domain/my_vhost"

Values of different types can be encoded. The example above encodes both binaries (<<"guest">>) and strings ("amqp://fred:secret@host1.domain/my_vhost").

The encryption mechanism uses PBKDF2 to produce a derived key from the passphrase. The default hash function is SHA512 and the default number of iterations is 1000. The default cipher is AES 256 CBC.

These defaults can be changed in the configuration file:

[
  {rabbit, [
      ...
      {config_entry_decoder, [
             {passphrase, "mypassphrase"},
             {cipher, blowfish_cfb64},
             {hash, sha256},
             {iterations, 10000}
         ]}
    ]}
].

Or using CLI tools:

rabbitmqctl encode --cipher blowfish_cfb64 --hash sha256 --iterations 10000 \
                     '<<"guest">>' mypassphrase

Configuration Using Environment Variables

Certain server parameters can be configured using environment variables: node name, RabbitMQ configuration file location, inter-node communication ports, Erlang VM flags, and so on.

Path and Directory Name Restrictions

Some of the environment variable configure paths and locations (node's base or data directory, plugin source and expansion directories, and so on). Those paths have must exclude a number of characters:

  • * and ? (on Linux, macOS, BSD and other UNIX-like systems)
  • ^ and ! (on Windows)
  • [ and ]
  • { and }

The above characters will render the node unable to start or function as expected (e.g. expand plugins and load their metadata).

Linux, MacOS, BSD

On UNIX-based systems (Linux, MacOS and flavours of BSD) it is possible to use a file named rabbitmq-env.conf to define environment variables that will be used by the broker. Its location is configurable using the RABBITMQ_CONF_ENV_FILE environment variable.

rabbitmq-env.conf uses the standard environment variable names but without the RABBITMQ_ prefix. For example, the RABBITMQ_CONFIG_FILE parameter appears below as CONFIG_FILE and RABBITMQ_NODENAME becomes NODENAME:

# Example rabbitmq-env.conf file entries. Note that the variables
# do not have the RABBITMQ_ prefix.
#
# Overrides node name
NODENAME=bunny@myhost

# Specifies new style config file location
CONFIG_FILE=/etc/rabbitmq/rabbitmq.conf

# Specifies advanced config file location
ADVANCED_CONFIG_FILE=/etc/rabbitmq/advanced.config

See the rabbitmq-env.conf man page for details.

Windows

The easiest option to customise names, ports or locations is to configure environment variables in the Windows dialogue: Start > Settings > Control Panel > System > Advanced > Environment Variables. Then create or edit the system variable name and value.

Alternatively it is possible to use a file named rabbitmq-env-conf.bat to define environment variables that will be used by the broker. Its location is configurable using the RABBITMQ_CONF_ENV_FILE environment variable.

Important: for environment changes to take effect on Windows, the service must be re-installed. It is not sufficient to restart the service.

This can be done using the installer or on the command line with administrator permissions:

  • Start an admin command prompt
  • cd into the sbin folder under the RabbitMQ server installation directory (such as C:\Program Files (x86)\RabbitMQ Server\rabbitmq_server-3.7.16\sbin)
  • Run rabbitmq-service.bat remove
  • Set environment variables via command line, i.e. run commands like the following:
    set RABBITMQ_BASE=C:\Data\RabbitMQ
  • Run rabbitmq-service.bat install

Alternatively, if the new configuration needs to take effect after the next broker restart, the service removal step can be skipped:

  • Start an admin command prompt
  • cd into the sbin folder under RabbitMQ server installation directory
  • Set environment variables via command line
  • Run rabbitmq-service.bat install, which will only update service parameters

RabbitMQ Environment Variables

All environment variables used by RabbitMQ use the prefix RABBITMQ_ (except when defined in rabbitmq-env.conf or rabbitmq-env-conf.bat).

Environment variables set in the shell environment take priority over those set in rabbitmq-env.conf or rabbitmq-env-conf.bat, which in turn override RabbitMQ built-in defaults.

The table below describes key environment variables that can be used to configure RabbitMQ. More variables are covered in the File and Directory Locations guide.

NameDefaultDescription
RABBITMQ_NODE_IP_ADDRESS the empty string, meaning that it should bind to all network interfaces. Change this if you only want to bind to one network interface. Binding to two or more interfaces can be set up in the configuration file.
RABBITMQ_NODE_PORT 5672
RABBITMQ_DIST_PORT RABBITMQ_NODE_PORT + 20000 Port used for inter-node and CLI tool communication. Ignored if node config file sets kernel.inet_dist_listen_min or kernel.inet_dist_listen_max keys. See Networking for details.
RABBITMQ_DISTRIBUTION_BUFFER_SIZE 128000 Outgoing data buffer size limit to use for inter-node communication connections, in kilobytes. Values lower than 64 MB are not recommended.
RABBITMQ_IO_THREAD_POOL_SIZE 128 (Linux), 64 (Windows) Number of threads used by the runtime for I/O. Values lower than 32 are not recommended.
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
  • Generic UNIX - $RABBITMQ_HOME/etc/rabbitmq/rabbitmq
  • Debian - /etc/rabbitmq/rabbitmq
  • RPM - /etc/rabbitmq/rabbitmq
  • MacOS(Homebrew) - ${install_prefix}/etc/rabbitmq/rabbitmq, the Homebrew prefix is usually /usr/local
  • Windows - %APPDATA%\RabbitMQ\rabbitmq
Main RabbitMQ config file path without the .conf (or .config, for the classic format) extension. For example, it should be /data/rabbitmq/rabbitmq, not /data/rabbitmq/rabbitmq.conf.
RABBITMQ_ADVANCED_CONFIG_FILE
  • Generic UNIX - $RABBITMQ_HOME/etc/rabbitmq/advanced
  • Debian - /etc/rabbitmq/advanced
  • RPM - /etc/rabbitmq/advanced
  • MacOS (Homebrew) - ${install_prefix}/etc/rabbitmq/advanced, the Homebrew prefix is usually /usr/local
  • Windows - %APPDATA%\RabbitMQ\advanced
"Advanced" (Erlang term-based) RabbitMQ config file path without the .config file extension. For example, it should be /data/rabbitmq/advanced, not /data/rabbitmq/advanced.config.
RABBITMQ_CONF_ENV_FILE
  • Generic UNIX package: $RABBITMQ_HOME/etc/rabbitmq/rabbitmq-env.conf
  • Ubuntu and Debian: /etc/rabbitmq/rabbitmq-env.conf
  • RPM: /etc/rabbitmq/rabbitmq-env.conf
  • MacOS (Homebrew) - ${install_prefix}/etc/rabbitmq/rabbitmq-env.conf, the Homebrew prefix is usually /usr/local
  • Windows - %APPDATA%\RabbitMQ\rabbitmq-env-conf.bat
Location of the file that contains environment variable definitions (without the RABBITMQ_ prefix). Note that the file name on Windows is different from other operating systems.
RABBITMQ_MNESIA_BASE
  • Generic UNIX package: $RABBITMQ_HOME/var/lib/rabbitmq/mnesia
  • Ubuntu and Debian packages: /var/lib/rabbitmq/mnesia/
  • RPM: /var/lib/rabbitmq/plugins
  • MacOS (Homebrew) - ${install_prefix}/var/lib/rabbitmq/mnesia, the Homebrew prefix is usually /usr/local
  • Windows - %APPDATA%\RabbitMQ
This base directory contains sub-directories for the RabbitMQ server's node database, message store and cluster state files, one for each node, unless RABBITMQ_MNESIA_DIR is set explicitly. It is important that effective RabbitMQ user has sufficient permissions to read, write and create files and subdirectories in this directory at any time. This variable is typically not overridden. Usually RABBITMQ_MNESIA_DIR is overridden instead.
RABBITMQ_MNESIA_DIR
  • Generic UNIX package: $RABBITMQ_MNESIA_BASE/$RABBITMQ_NODENAME
  • Ubuntu and Debian packages: $RABBITMQ_MNESIA_BASE/$RABBITMQ_NODENAME
  • RPM: $RABBITMQ_MNESIA_BASE/$RABBITMQ_NODENAME
  • MacOS (Homebrew) - ${install_prefix}/var/lib/rabbitmq/mnesia/$RABBITMQ_NODENAME, the Homebrew prefix is usually /usr/local
  • Windows - %APPDATA%\RabbitMQ\`$RABBITMQ_NODENAME`
The directory where this RabbitMQ node's data is stored. This s a schema database, message stores, cluster member information and other persistent node state.
RABBITMQ_PLUGINS_DIR
  • Generic UNIX package: $RABBITMQ_HOME/plugins
  • Ubuntu and Debian packages: /var/lib/rabbitmq/plugins
  • RPM: /var/lib/rabbitmq/plugins
  • MacOS (Homebrew) - $RABBITMQ_HOME/plugins, with Homebrew $RABBITMQ_HOME is ${install_prefix}/Cellar/rabbitmq/${version} and installation prefix is usually /usr/local.
  • Windows: %RABBITMQ_HOME%\plugins
The list of directories where plugin archive files are located and extracted from. This is PATH-like variable, where different paths are separated by an OS-specific separator (: for Unix, ; for Windows). Plugins can be installed to any of the directories listed here. Must not contain any characters mentioned in the path restriction section.
RABBITMQ_PLUGINS_EXPAND_DIR
  • Generic UNIX package: $RABBITMQ_MNESIA_BASE/$RABBITMQ_NODENAME-plugins-expand
  • Ubuntu and Debian packages: $RABBITMQ_MNESIA_BASE/$RABBITMQ_NODENAME-plugins-expand
  • RPM: $RABBITMQ_MNESIA_BASE/$RABBITMQ_NODENAME-plugins-expand
  • MacOS (Homebrew) - ${install_prefix}/var/lib/rabbitmq/mnesia/$RABBITMQ_NODENAME-plugins-expand, the Homebrew prefix is usually /usr/local
  • Windows - %APPDATA%\RabbitMQ\$RABBITMQ_NODENAME-plugins-expand
The directory the node expand (unpack) plugins to and use it as a code path location. Must not contain any characters mentioned in the path restriction section.
RABBITMQ_USE_LONGNAME When set to true this will cause RabbitMQ to use fully qualified names to identify nodes. This may prove useful on EC2. Note that it is not possible to switch between using short and long names without resetting the node.
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% 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_SERVER_CODE_PATH None

Extra code path (a directory) to be specified when starting the runtime. Will be passed to the erl command when a node is started.

Typically used in combination with rabbitmqctl hipe_compile to precompile key RabbitMQ modules with HiPE (a JIT runtime compile) and avoid the HiPE startup penalty. When set to a directory with precompiled modules, the HiPE-compiled versions will be detected, loaded and skipped for compilation.

hipe_compile must be set to true in node cofiguration.

RABBITMQ_CTL_ERL_ARGS None Parameters for the erl command used when invoking rabbitmqctl. This could be set to specify a range of ports to use for Erlang distribution:
-kernel inet_dist_listen_min 35672
-kernel inet_dist_listen_max 35680
RABBITMQ_SERVER_ERL_ARGS
  • Unix*: +P 1048576 +t 5000000 +stbt db +zdbbl 128000
  • 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 to 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.

Besides the variables listed above, there are several environment variables which tell RabbitMQ where to locate its database, log files, plugins, configuration and so on.

Finally, some environment variables are operating system-specific.

NameDefaultDescription
HOSTNAME
  • Unix, Linux: env hostname
  • MacOS: 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.

Operating System Kernel Limits

Most operating systems enforce limits on kernel resources: virtual memory, stack size, open file handles and more. To Linux users these limits can be known as "ulimit limits".

RabbitMQ nodes are most commonly affected by the maximum open file handle limit. Default limit value on most Linux distributions is usually 1024, which is very low for a messaging broker (or generally, any data service). See Production Checklist for recommended values.

Modifying Limits

With systemd (Modern Linux Distributions)

On distributions that use systemd, the OS limits are controlled via a configuration file at /etc/systemd/system/rabbitmq-server.service.d/limits.conf. For example, to set the max open file handle limit (nofile) to 64000:

[Service]
LimitNOFILE=64000

See systemd documentation to learn about the supported limits and other directives.

With Docker

To configure kernel limits for Docker contains, use the "default-ulimits" key in Docker daemon configuration file. The file has to be installed on Docker hosts at /etc/docker/daemon.json:

{
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 64000,
      "Soft": 64000
    }
  }
}

Without systemd (Older Linux Distributions)

The most straightforward way to adjust the per-user limit for RabbitMQ on distributions that do not use systemd is to edit the /etc/default/rabbitmq-server (provided by the RabbitMQ Debian package) or rabbitmq-env.conf to invoke ulimit before the service is started.

ulimit -S -n 4096

This soft limit cannot go higher than the hard limit (which defaults to 4096 in many distributions). The hard limit can be increased via /etc/security/limits.conf. This also requires enabling the pam_limits.so module and re-login or reboot.

Note that limits cannot be changed for running OS processes.

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!