When you change the default settings for a document Which of the following files is changed

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 variables
• 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. 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:

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, usually 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 New 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.

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

%% 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

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.

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:

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.conf is translated into the internally used (advanced) config format. These configuration is merged into the defaults
• advanced.config is 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:

• rabbitmq.conf.example
• advanced.config.example

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

listeners.tcp.default = 5672

num_acceptors.tcp = 10

handshake_timeout = 10000

num_acceptors.ssl = 10

ssl_options = none

ssl_handshake_timeout = 5000

vm_memory_high_watermark.relative = 0.6

vm_memory_high_watermark.absolute = 2GB

vm_memory_high_watermark.relative = 0.4

vm_memory_calculation_strategy = allocated

vm_memory_high_watermark_paging_ratio = 0.5

disk_free_limit.relative = 3.0

disk_free_limit.absolute = 2GB

disk_free_limit.absolute = 50MB

log.file.level = info

channel_max = 2047

channel_operation_timeout = 15000

heartbeat = 60

default_vhost = /

default_user = guest

default_pass = guest

default_user_tags.administrator = true

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

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

loopback_users.monitoring = true

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

cluster_formation.classic_config.nodes.1 = rabbit@hostname1
cluster_formation.classic_config.nodes.2 = rabbit@hostname2

collect_statistics = none

collect_statistics_interval = 5000

management_db_cache_multiplier = 5

auth_mechanisms.1 = PLAIN
auth_mechanisms.2 = AMQPLAIN

auth_backends.1 = internal

reverse_dns_lookups = false

delegate_count = 16

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

tcp_listen_options.keepalive = false

cluster_partition_handling = ignore

cluster_keepalive_interval = 10000

queue_index_embed_msgs_below = 4096

mnesia_table_loading_retry_timeout = 30000

mnesia_table_loading_retry_limit = 10

mirroring_sync_batch_size = 4096

queue_master_locator = client-local

proxy_protocol = false

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

{rabbit, [
{msg_store_index_module, rabbit_msg_store_ets_index}
]}

{rabbit, [
{backing_queue_module, rabbit_variable_queue}
]}

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

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

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

{rabbit, [
{queue_index_max_journal_entries, 32768}
]}

{rabbit, [
{lazy_queue_explicit_gc_run_operation_threshold, 1000}
]}

{rabbit, [
{queue_explicit_gc_run_operation_threshold, 1000}
]}

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

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:/my_vhost"' mypassphrase
{encrypted,<<"... long encrypted value...">>}

Or, on Windows:

rabbitmqctl encode "<<""guest"">>" mypassphrase
{encrypted,<<"... long encrypted value...">>}
rabbitmqctl encode '"amqp://fred:/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:/my_vhost"

Or, on Windows:

rabbitmqctl decode "{encrypted, <<""..."">>}" mypassphrase
<<"guest">>
rabbitmqctl decode "{encrypted, <<""..."">>}" mypassphrase
"amqp://fred:/my_vhost"

Values of different types can be encoded. The example above encodes both binaries (<<"guest">>) and strings ("amqp://fred:/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

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 stop to stop the service
• Run rabbitmq-service.bat remove to 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.

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.

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!

What are the default page settings for a Word document?

What means making changes to the default setting of a page?

What is the default view when you open a document or create a new document?

Which of the following selects a Word in an existing document?