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:
- Different ways in which various settings of the server and plugins are configured
- Configuration file(s): primary rabbitmq.conf or a directory of .conf files, and optional advanced.config
- Default configuration file location(s) on various platforms
- Configuration troubleshooting: how to find config file location and inspect and verify effective configuration
- Environment variable interpolation in
rabbitmq.conf - Environment variables used by RabbitMQ nodes
- Operating system (kernel) limits
- Available core server settings
- Available environment variables
- How to encrypt sensitive configuration values
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. Deployment Guidelines 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 |
Contains server and plugin settings for TCP listeners and other networking-related settings, TLS, resource constraints (alarms), authentication and authorisation backends, message store settings, and more. | |
Used to define node name, file and directory locations, runtime flags taken from the shell, or set in
the environment configuration file, | |
When internal authentication/authorisation backend is used,
| |
| |
| |
| |
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. | |
Control lower-level aspects of the system: memory allocation settings, inter-node communication buffer size, runtime scheduler settings and more. | |
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 main configuration file named rabbitmq.conf.
This includes configuration for the core server as well as plugins. An additional configuration file can be used to configure settings that cannot be expressed in the main file's configuration format. This is covered in more details below.
The sections below cover the syntax and location of both files, where to find examples, and more.
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, consult the log file and/or management UI as explained in the following section.
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, the location of configuration files used by a local node, use the rabbitmq-diagnostics status command:
# displays key
rabbitmq-diagnostics status
and look for the Config files section that would look like this:
Config files
* /etc/rabbitmq/advanced.config
* /etc/rabbitmq/rabbitmq.conf
To inspect the locations of a specific node, including nodes running remotely, use the -n (short for --node) switch:
rabbitmq-diagnostics status -n [node name]
Finally, 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 verifying effective node configuration. Together, these steps help quickly narrow down most common misconfiguration problems.
The Modern and Old Config File Formats
All supported RabbitMQ versions use an ini-like, sysctl configuration file format
for the main configuration file. The file is typically named rabbitmq.conf.
The new config format is much simpler, easier for humans to read 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, modern RabbitMQ versions allow for both formats to be used at the same time
in separate files: rabbitmq.conf uses the new style format and is recommended for most settings,
and advanced.config covers more advanced settings that the ini-style configuration
cannot express. This is covered in more detail in the following sections.
| Configuration File | Format Used | Purpose |
rabbitmq.conf | New style format (sysctl or ini-like) | Primary configuration file with a |
advanced.config | Classic (Erlang terms) | A limited number of settings that cannot be expressed in the new style configuration format, such as LDAP queries. Only should be used when necessary. |
rabbitmq-env.conf (rabbitmq-env.conf.bat on Windows) | Environment variable pairs | Used to set environment variables relevant to RabbitMQ in one place. |
Compare this examplary rabbitmq.conf file
# A new style format snippet. This format is used by rabbitmq.conf files.
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
to
%% A classic format snippet, now used by advanced.config files.
[
{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}]}]}
].
The Main Configuration File, rabbitmq.conf
The configuration file rabbitmq.conf
allows the RabbitMQ server and plugins to be configured.
The file uses the sysctl format,
unlike advanced.config and the original rabbitmq.config (both use the Erlang terms 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:
%% this is a comment
[
{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 contain many examples in relevant 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
(or RABBITMQ_CONFIG_FILES to use a conf.d-style directory of sorted files) environment variables.
Use .conf as file extension for the new style config format, e.g. /etc/rabbitmq/rabbitmq.conf or
/data/configuration/rabbitmq/rabbitmq.conf
Using a Directory of .conf Files
A conf.d-style directory of files can also be used. Use RABBITMQ_CONFIG_FILES (note the plural "_FILES")
to point the node at a directory of such files:
# uses a directory of .conf files loaded in alphabetical order
RABBITMQ_CONFIG_FILES=/path/to/a/custom/location/rabbitmq/conf.d
Target directory must contain a number of .conf files with the same syntax as rabbitmq.conf.
They will be loaded in alphabetical order. A common naming practice uses numerical prefixes in filenames to make it easier to reason about the order, or make sure a "defaults file" is always loaded first, regardless of how many extra files are generated at deployment time:
ls -lh /path/to/a/custom/location/rabbitmq/conf.d
# => -r--r--r-- 1 rabbitmq rabbitmq 87B Mar 21 19:50 00-defaults.conf
# => -r--r--r-- 1 rabbitmq rabbitmq 4.6K Mar 21 19:52 10-main.conf
# => -r--r--r-- 1 rabbitmq rabbitmq 1.6K Mar 21 19:52 20-tls.conf
# => -r--r--r-- 1 rabbitmq rabbitmq 1.6K Mar 21 19:52 30-federation.conf
Environment Variable Interpolation in rabbitmq.conf
Modern RabbitMQ versions support environment variable interpolation in rabbitmq.conf. For example,
to override default user credentials, one can use import a definition file
or the following config file in combination with two environment variables:
# environment variable interpolation
default_user = $(SEED_USERNAME)
default_pass = $(SEED_USER_PASSWORD)
Environment variables can be used to configure a portion of a value, for example, cluster name:
cluster_name = deployment-$(DEPLOYMENT_ID)
Environment variable values are interpolated as strings before the config file is parsed and validated. This means that they can be used to override numerical settings (such as ports) or paths (such as TLS certificate and private key paths).
In addition, RabbitMQ respects a number of environment variables for when a value must be known before the configuration file is loaded.
The advanced.config File
This section describes the original configuration format that has been superseded by a modern alternative.
Only a limited number of features and advanced (or rarely used) settings require the use
of this format. When this is an option, use rabbitmq.conf.
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.
Location of rabbitmq.conf, advanced.config and rabbitmq-env.conf
Default configuration file location is distribution-specific. RabbitMQ packages or nodes will not create any configuration files. Users and deployment tool should use the following locations when creating the files:
| Platform | Default Configuration File Directory | Example Configuration File Paths |
|
| |
|
| |
|
| |
|
| |
|
|
Environment variables can be used to override the location of the configuration file:
# overrides primary config file location
RABBITMQ_CONFIG_FILE=/path/to/a/custom/location/rabbitmq.conf
# overrides advanced config file location
RABBITMQ_ADVANCED_CONFIG_FILE=/path/to/a/custom/location/advanced.config
# overrides environment variable file location
RABBITMQ_CONF_ENV_FILE=/path/to/a/custom/location/rabbitmq-env.conf
When Will Configuration File Changes Be Applied
rabbitmq.conf and advanced.config changes take effect after a node restart.
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.
Windows service users will need to re-install the service if configuration file location or any values in ``rabbitmq-env-conf.bat` have changed. Environment variables used by the service would not be updated otherwise.
In the context of deployment automation this means that environment variables
such as RABBITMQ_BASE and RABBITMQ_CONFIG_FILE should ideally be set before RabbitMQ is installed.
This would help avoid unnecessary confusion and Windows service re-installations.
How to Inspect and Verify Effective Configuration of a Running Node
It is possible to print effective configuration (user provided values from all configuration files merged into defaults) using the rabbitmq-diagnostics environment command:
# inspect effective configuration on a node
rabbitmq-diagnostics environment
to check effective configuration of a specific node, including nodes running remotely, use the -n (short for --node) switch:
rabbitmq-diagnostics environment -n [node name]
The command above will print applied configuration for every application (RabbitMQ, plugins, libraries) running on the node. Effective configuration is computed using the following steps:
rabbitmq.confis translated into the internally used (advanced) config format. These configuration is merged into the defaultsadvanced.configis loaded if present, and merged into the result of the step above
Effective configuration should be verified together with config file location. Together, these steps help quickly narrow down most common misconfiguration problems.
The rabbitmq.config (Classic Format) File
Prior to RabbitMQ 3.7.0, RabbitMQ config file was named
rabbitmq.config and used the same Erlang term format used by advanced.config today.
That format is still supported for backwards compatibility.
The classic format is deprecated. Please prefer the new style config format
in rabbitmq.conf accompanied by an advanced.config file as needed.
To use a config file in the classic format, export RABBITMQ_CONFIG_FILE to point to the file with
a .config extension. The extension will indicate to RabbitMQ that it should treat the file as one
in the classic config format.
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.
Example Configuration Files
The RabbitMQ server source repository contains examples for the configuration files:
These files contain examples of most of the configuration keys along with a brief explanation 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.13.7/,
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.tcp | 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.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: |
ssl_options | TLS configuration. See the TLS guide. Default: |
num_acceptors.tcp | Number of Erlang processes that will accept connections for the TCP listeners. Default: |
num_acceptors.ssl | Number of Erlang processes that will accept TLS connections from clients. Default: |
distribution.listener.interface | Controls what network interface will be used for communication with other cluster members and CLI tools. Default: |
distribution.listener.port_range.min | Controls the lower bound of a server port range that will be used for communication with other cluster members and CLI tools. Default: |
distribution.listener.port_range.max | Controls the upper bound of a server port range that will be used for communication with other cluster members and CLI tools. Default: |
handshake_timeout | Maximum time for AMQP 0-9-1 handshake (after socket connection and TLS handshake), in milliseconds. Default: |
ssl_handshake_timeout | TLS handshake timeout, in milliseconds. Default: |
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: See the memory-based flow control and alarms documentation. Default: |
vm_memory_calculation_strategy | Strategy for memory usage reporting. Can be one of the following:
Default: |
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: |
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 Default: |
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 By default free disk space must exceed 50MB. This must be revisited for production environments. See the Disk Alarms documentation. Default: |
queue_leader_locator | Controls the strategy used when selecting a node to host the leader replica of a newly declared queue or stream. |
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 Default: |
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_operation_timeout | Channel operation timeout in milliseconds (used internally, not directly exposed to clients due to messaging protocol differences and limitations). Default: |
max_message_size | The largest allowed message payload size in bytes. Messages of larger size will be rejected with a suitable channel exception. Default: Max value: |
heartbeat | Value representing the heartbeat timeout suggested by the server during connection parameter negotiation. If set to 0 on both ends, heartbeats are deactivated (this is not recommended). See the Heartbeats guide for details. Default: |
default_vhost | Virtual host to create when RabbitMQ creates a new
database from scratch. The
exchange Default: |
default_user | User name to create when RabbitMQ creates a new database from scratch. Default: |
default_pass | Password for the default user. Default: |
default_user_tags | Tags for the default user. Default: |
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. To allow the default To restrict another user to localhost-only connections,
do it like so ( Default: |
cluster_formation.classic_config.nodes | Classic peer discovery backend's list of nodes to contact. For example, to cluster with nodes Default: |
collect_statistics | Statistics collection mode. Primarily relevant for the management plugin. Options are:
Default: |
collect_statistics_interval | Statistics collection interval in milliseconds. Primarily relevant for the management plugin. Default: |
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: |
auth_mechanisms | SASL authentication mechanisms to offer to clients. Default: |
auth_backends | List of authentication and authorisation backends to use. See the access control guide for details and examples. Other databases
than Default: |
reverse_dns_lookups | Set to Default: |
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: |
tcp_listen_options | Default socket options. You may want to change these when you troubleshoot network issues. Default: Set Set |
cluster_partition_handling | How to handle network partitions. Available modes are:
See the documentation on partitions for more information. Default: |
cluster_keepalive_interval | How frequently nodes should send keepalive messages to
other nodes (in milliseconds). Note that this is not the
same thing as Default: |
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: |
mnesia_table_loading_retry_timeout | Timeout used when waiting for Mnesia tables in a cluster to become available. Default: |
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: |
mirroring_sync_batch_size | Batch size used to transfer messages to an unsynchronised replica (queue mirror). See documentation on eager batch synchronization. Default: |
queue_leader_locator | queue leader location strategy. Available strategies are:
See the documentation on queue leader location for more information. Default: |
proxy_protocol | If set to See the networking guide for more information. Default: |
cluster_name | Operator-controlled cluster name. This name is used to identify a cluster, and by
the federation and Shovel plugins to record the origin or path of transferred messages.
Can be set to any arbitrary string to help identify the cluster (eg. Default: by default the name is derived from the first (seed) node in the cluster. |
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: |
backing_queue_module | Implementation module for queue contents. Default: |
msg_store_file_size_limit | Message store segment file size. Changing this for a node with an existing (initialised) database is dangerous and can lead to data loss! Default: |
trace_vhosts | Used internally by the tracer. You shouldn't change this. Default: |
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: |
queue_index_max_journal_entries | After how many queue index journal entries it will be flushed to disk. Default: |
Several plugins that ship with RabbitMQ have dedicated documentation guides that cover plugin configuration:
- rabbitmq_management
- rabbitmq_management_agent
- rabbitmq_stomp
- rabbitmq_mqtt
- rabbitmq_shovel
- rabbitmq_federation
- rabbitmq_auth_backend_ldap
- rabbitmq_auth_backend_oauth
Configuration Value Encryption
Sensitive advanced.config entries (e.g. password, URL containing
credentials) can be encrypted. RabbitMQ nodes then decrypt encrypted entries on boot.
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}.
Encrypting advanced.config Values Using CLI Tools
Use rabbitmqctl and the encode
command to encrypt values:
# <<"guest">> here is a value to encode, as an Erlang binary,
# as it would have appeared in advanced.config
rabbitmqctl encode '<<"guest">>' mypassphrase
{encrypted,<<"... long encrypted value...">>}
# "amqp://fred:secret@host1.domain/my_vhost" here is a value to encode, provided as an Erlang string,
# as it would have appeared in advanced.config
rabbitmqctl encode '"amqp://fred:secret@host1.domain/my_vhost"' mypassphrase
{encrypted,<<"... long encrypted value...">>}
Or, on Windows:
# <<"guest">> here is a value to encode, as an Erlang binary,
# as it would have appeared in advanced.config
rabbitmqctl encode "<<""guest"">>" mypassphrase
{encrypted,<<"... long encrypted value...">>}
# "amqp://fred:secret@host1.domain/my_vhost" here is a value to encode, provided as an Erlang string,
# as it would have appeared in advanced.config
rabbitmqctl encode '"amqp://fred:secret@host1.domain/my_vhost"' mypassphrase
{encrypted,<<"... long encrypted value...">>}
Decrypting advanced.config Values Using CLI Tools
Use the decode command to decrypt values:
rabbitmqctl decode '{encrypted, <<"...">>}' mypassphrase
# => <<"guest">>
rabbitmqctl decode '{encrypted, <<"...">>}' mypassphrase
# => "amqp://fred:secret@host1.domain/my_vhost"
Or, on Windows:
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").
Encryption Settings: Cipher, Hashing Function, Number of Iterations
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
Or, on Windows:
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 variable 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.
Windows service users will need to re-install the service if configuration file location or any values in ``rabbitmq-env-conf.bat` changed. Environment variables used by the service would not be updated otherwise.
This can be done using the installer or on the command line with administrator permissions:
- Start an administrative command prompt
- cd into the sbin folder under the RabbitMQ server installation directory (such as
C:\Program Files (x86)\RabbitMQ Server\rabbitmq_server-{version}\sbin) - Run
rabbitmq-service.bat stopto stop the service - Run
rabbitmq-service.bat removeto remove the Windows service (this will not remove RabbitMQ or its data directory) - Set environment variables via command line, i.e. run commands like the following:
set RABBITMQ_BASE=C:\Data\RabbitMQ - Run
rabbitmq-service.bat install - Run
rabbitmq-service.bat start
This will restart the node in a way that makes the environment variable and
rabbitmq-env-conf.bat changes to be observable to it.
Environment Variables Used by RabbitMQ
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.
| Name | Description |
|---|---|
| RABBITMQ_NODE_IP_ADDRESS | 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. Default: an empty string, meaning "bind to all network interfaces". |
| RABBITMQ_NODE_PORT | See Networking guide for more information on ports used by various parts of RabbitMQ. Default: 5672. |
| RABBITMQ_DIST_PORT | Port used for inter-node and CLI tool communication. Ignored if node config
file sets Default: |
| ERL_MAX_PORTS | This limit corresponds to the maximum open file handle limit in the kernel.
When the latter is set to a value higher than 65536, Default: 65536 |
| ERL_EPMD_ADDRESS | Interface(s) used by epmd, a component in inter-node and CLI tool communication. Default: all available interfaces, both IPv6 and IPv4. |
| ERL_EPMD_PORT | Port used by epmd, a component in inter-node and CLI tool communication. Default: |
| RABBITMQ_DISTRIBUTION_BUFFER_SIZE | Outgoing data buffer size limit to use for inter-node communication connections, in kilobytes. Values lower than 64 MB are not recommended. Default: 128000 |
| RABBITMQ_NODENAME | The node name should be unique per Erlang-node-and-machine combination. To run multiple nodes, see the clustering guide. Default:
|
| RABBITMQ_CONFIG_FILE | Main RabbitMQ config file path, for example,
Default:
|
| RABBITMQ_CONFIG_FILES | Path to a directory of RabbitMQ configuration files in the new-style (.conf) format. The files will be loaded in alphabetical order. Prefixing each files with a number is a common practice. Default:
|
| RABBITMQ_ADVANCED_CONFIG_FILE | "Advanced" (Erlang term-based) RabbitMQ config file path with a Default:
|
| RABBITMQ_CONF_ENV_FILE | Location of the file that contains environment variable definitions (without the Default:
|
| RABBITMQ_LOG_BASE | Can be used to override log files directory location. Default:
|
| RABBITMQ_MNESIA_BASE | 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 Default:
|
| RABBITMQ_MNESIA_DIR | The directory where this RabbitMQ node's data is stored. This includes a schema database, message stores, cluster member information and other persistent node state. Default:
|
| RABBITMQ_PLUGINS_DIR | The list of directories where plugin archive files are located and extracted
from. This is Default:
|
| RABBITMQ_PLUGINS_EXPAND_DIR | 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. Default:
|
| RABBITMQ_USE_LONGNAME | When set to Default: |
| RABBITMQ_SERVICENAME | The name of the installed Windows service. This will appear in
Default: RabbitMQ. |
| RABBITMQ_CONSOLE_LOG | Set this variable to
Default: (none) |
| RABBITMQ_SERVER_CODE_PATH | Extra code path (a directory) to be specified when starting the runtime.
Will be passed to the Default: (none) |
| RABBITMQ_CTL_ERL_ARGS | Parameters for the Default: (none) |
| RABBITMQ_SERVER_ERL_ARGS | Standard parameters for the Default:
|
| RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS | Additional parameters for the Default:
|
| RABBITMQ_SERVER_START_ARGS | Extra parameters for the Default: (none) |
| RABBITMQ_DEFAULT_USER | This environment variable is only meant to be used in development and CI environments.
This has the same meaning as Default: (none) |
| RABBITMQ_DEFAULT_PASS | This environment variable is only meant to be used in development and CI environments.
This has the same meaning as Default: (none) |
| RABBITMQ_DEFAULT_VHOST | This environment variable is only meant to be used in development and CI environments.
This has the same meaning as Default: (none) |
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.
| Name | Description |
|---|---|
| HOSTNAME | The name of the current machine. Default:
|
| COMPUTERNAME | The name of the current machine. Default:
|
| ERLANG_SERVICE_MANAGER_PATH | This path is the location of Default:
|
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 Deployment Guidelines 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 containers, 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.