Configuration
RabbitMQ comes with default built-in settings which will most likely be sufficient for running your RabbitMQ server effectively. If it runs fine, then you probably don't need any configuration at all.
If you have other constraints, RabbitMQ provides three general ways to customise the server:
- environment variables
- define ports, file locations and names (taken from the shell, or set in the rabbitmq-env.conf file)
- a configuration file
- defines server component settings for permissions, limits and clusters, and also plugin settings.
- runtime parameters and policies
- defines cluster-wide settings which can change at run time
Verify Configuration
The active configuration can be verified in the broker log, e.g. the active configuration file:
config file(s) : /etc/rabbitmq/rabbitmq.config
will show up in the log file.
Customise RabbitMQ Environment
Unix (general)
On Unix-based systems (including Linux, MacOSX) you can create/edit rabbitmq-env.conf to define environment variables. Its location is not configurable (unlike rabbitmq.config).
Use the standard environment variable names (but drop the RABBITMQ_ prefix) e.g.
#example rabbitmq-env.conf file entries #Rename the node NODENAME=bunny@myhost #Config file location and new filename bunnies.config CONFIG_FILE=/etc/rabbitmq/testdir/bunniesMore info on using rabbitmq-env.conf
Windows
If you need to customise names, ports, locations, it is easiest to configure environment variables in the Windows dialogue: Start > Settings > Control Panel > System > Advanced > Environment Variables.
Create or edit the system variable name and value. For environment changes to take effect, open a new Command Prompt, then restart the broker or re-install the service.
RabbitMQ Environment Variables
RabbitMQ environment variable names have the prefix RABBITMQ_. A typical variable called RABBITMQ_var_name is set as follows:
- a shell environment variable called RABBITMQ_var_name is used if this is defined;
- otherwise, a variable called var_name is used if this is set in the rabbitmq-env.conf file;
- otherwise, a system-specified default value is used.
In this way, variables set in the shell environment take priority over variables set in rabbitmq-env.conf, which in turn over-ride RabbitMQ built-in defaults.
It is unlikely you will need to set any of these environment variables. If you have non-standard requirements, then RabbitMQ environment variables include, but are not limited to:
| Name | Default | Description |
|---|---|---|
| RABBITMQ_NODE_IP_ADDRESS | the empty string - meaning bind to all network interfaces. | Change this if you only want to bind to one network interface. |
| RABBITMQ_NODE_PORT | 5672 | |
| RABBITMQ_NODENAME |
|
The node name should be unique per erlang-node-and-machine combination. To run multiple nodes, see the clustering guide. |
| RABBITMQ_SERVICENAME | Windows Service: RabbitMQ | The name of the installed service. This will appear in services.msc. |
| RABBITMQ_CONSOLE_LOG | Windows Service: |
Set this variable to new or reuse
to redirect console output from the server to a file named
%RABBITMQ_SERVICENAME%.debug in the
default RABBITMQ_BASE directory.
|
| RABBITMQ_CTL_ERL_ARGS | None | Parameters for the erl command used when invoking rabbitmqctl. This should be overridden for debugging purposes only. |
| RABBITMQ_SERVER_ERL_ARGS |
|
Standard parameters for the erl command used when invoking the RabbitMQ Server. This should be overridden for debugging purposes only. |
| 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. |
In addition, there are several environment variables which tell RabbitMQ where to locate its database, log files, plugins, configuration etc.
Other variables upon which RabbitMQ depends are:
| Name | Default | Description |
|---|---|---|
| HOSTNAME |
|
The name of the current machine |
| COMPUTERNAME | Windows: localhost | The name of the current machine |
| ERLANG_SERVICE_MANAGER_PATH | Windows Service: %ERLANG_HOME%\erts-x.x.x\bin | This path is the location of erlsrv.exe, the Erlang service wrapper script. |
Configuration File
The rabbitmq.config File
The configuration file rabbitmq.config allows the RabbitMQ core application, Erlang services and RabbitMQ plugins to be configured. It is a standard Erlang configuration file, documented on the Erlang Config Man Page.
An example configuration file follows:
[
{mnesia, [{dump_log_write_threshold, 1000}]},
{rabbit, [{tcp_listeners, [5673]}]}
].
This example will alter the dump_log_write_threshold for mnesia (increasing from the default of 100), and alter the port RabbitMQ listens on from 5672 to 5673.
This configuration file is not the same as rabbitmq-env.conf, which can be used to set environment variables on non-windows systems. A future release of RabbitMQ will unify the two configuration mechanisms.
Location of rabbitmq.config and rabbitmq-env.conf
The location of these files is distribution-specific. By default, they are not created, but expect to be located in the following places on each platform:
- Generic UNIX - $RABBITMQ_HOME/etc/rabbitmq/
- Debian - /etc/rabbitmq/
- RPM - /etc/rabbitmq/
- Mac OS X (Macports) - ${install_prefix}/etc/rabbitmq/, the Macports prefix is usually /opt/local
- Windows - %APPDATA%\RabbitMQ\
If rabbitmq-env.conf doesn't exist, it can be created manually in the default location only. It is not used on Windows systems.
If rabbitmq.config doesn't exist, it can be created manually. Set the RABBITMQ_CONFIG_FILE environment variable if you change the location. The Erlang runtime automatically appends the .config extension to the value of this variable.
Restart the server after changes. Windows service users need to take additional steps when changing plugins.
Variables Configurable in rabbitmq.config
Many users of RabbitMQ never need to change any of these values, and some are fairly obscure. However, for completeness they are all listed here.
| Key | Documentation |
|---|---|
| tcp_listeners |
List of ports on which to listen for AMQP connections
(without SSL). Can contain integers (meaning "listen on
all interfaces") or tuples such as {"127.0.0.1",
5672} to listen on a single interface.
Default: [5672] |
| ssl_listeners |
As above, for SSL connections.
Default: [] |
| ssl_options |
SSL configuration. See the SSL
documentation.
Default: [] |
| vm_memory_high_watermark |
Memory threshold at which the flow control is
triggered. See
the memory-based flow
control documentation.
Default: 0.4 |
| disk_free_limit |
Disk free space limit of the partition on which RabbitMQ
is storing data. When available disk space falls below
this limit, flow control is triggered. The value may be
set relative to the total amount of RAM (e.g.
{mem_relative, 1.0}). The value may also be
set to an integer number of bytes. By default free disk
space must exceed 1GB. See
the memory-based flow
control documentation.
Default: 1000000000 |
| log_levels |
Controls the granularity of logging. The value is a list
of log event category and log level pairs.
The level can be one of 'none' (no events are logged), 'error' (only errors are logged), 'warning' (only errors and warning are logged), or 'info' (errors, warnings and informational messages are logged). At present there is just one category defined - 'connection', for all events relating to network connections. Other, currently uncategorised, events are always logged. Default: [{connection, info}] |
| frame_max |
Maximum permissible size of a frame (in bytes) to
negotiate with clients. Setting to 0 means "unlimited"
but will trigger a bug in some QPid clients. Setting a
larger value may improve throughput; setting a smaller
value may improve latency.
Default: 131072 |
| heartbeat |
Value representing the heartbeat delay, in seconds, that the
server sends in the connection.tune frame. If set to
0, heartbeats are disabled. Clients might not follow the server
suggestion, see the AMQP
reference for more details. Disabling heartbeats might improve
performance in situations with a great number of connections, but
might lead to connections dropping in the presence of network
devices that close inactive connections.
Default: 600 |
| default_vhost |
Virtual host to create when RabbitMQ creates a new
database from scratch. The
exchange amq.rabbitmq.log will exist in
this virtual host.
Default: <<"/">> |
| default_user |
User name to create when RabbitMQ creates a new database
from scratch.
Default: <<"guest">> |
| default_pass |
Password for the default user.
Default: <<"guest">> |
| default_user_tags |
Tags for the default user.
Default: [administrator] |
| default_permissions |
Permissions
to assign to the default user when creating it.
Default: [<<".*">>, <<".*">>, <<".*">>] |
| cluster_nodes |
Set this to cause clustering to happen automatically. The
first element of the tuple is the nodes that the node will try to
cluster to. The second element is either disc or
ram and determines the node type.
Default: {[], disc} |
| server_properties |
List of key-value pairs to announce to clients on connection.
Default: [] |
| collect_statistics |
Statistics collection mode. Primarily relevant for the
management plugin. Options are:
Default: none |
| collect_statistics_interval |
Statistics collection interval in
milliseconds. Primarily relevant for
the management
plugin.
Default: 5000 |
| auth_mechanisms |
SASL authentication
mechanisms to offer to clients.
Default: ['PLAIN', 'AMQPLAIN'] |
| auth_backends |
List of authentication databases to use. Other databases
than rabbit_auth_backend_internal are
available through plugins.
Default: [rabbit_auth_backend_internal] |
| delegate_count |
Number of delegate processes to use for intra-cluster
communication. On a machine which has a very large
number of cores and is also part of a cluster, you may
wish to increase this value.
Default: 16 |
| trace_vhosts |
Used internally by
the tracer. You shouldn't
change this.
Default: [] |
| tcp_listen_options |
Default socket options. You probably don't want to
change this.
Default: [binary, {packet, raw},
{reuseaddr, true},
{backlog, 128},
{nodelay, true},
{exit_on_close, false}]
|
| hipe_compile |
Set to true to precompile parts of RabbitMQ
with the High Performance Erlang compiler. This will
increase the message rate that the server can handle,
while also increasing startup time.
You might see 20-50% better performance at the cost of approximately 1 minute delay at startup. These figures are highly workload- and hardware-dependent. HiPE support may not be compiled into your Erlang installation. If it is not, enabling this option will just cause a warning message to be displayed and startup will proceed as normal. For example, Debian / Ubuntu users will need to install the erlang-base-hipe package. HiPE is not available at all on some platforms, notably including Windows. This option should be considered experimental. If your Erlang VM segfaults, disable this option again. Default: false |
| cluster_partition_handling |
How to handle network partitions. One
of ignore,
pause_minority
or autoheal. See
the documentation
on partitions for more information.
Default: ignore |
| msg_store_index_module |
Implementation module for queue indexing. You probably
don't want to change this.
Default: rabbit_msg_store_ets_index |
| backing_queue_module |
Implementation module for queue contents. You probably
don't want to change this.
Default: rabbit_variable_queue |
| msg_store_file_size_limit |
Tunable value for the persister. You almost certainly
should not change this.
Default: 16777216 |
| queue_index_max_ journal_entries |
Tunable value for the persister. You almost certainly
should not change this.
Default: 65536 |
In addition, many plugins can have sections in the configuration file, with names of the form rabbitmq_plugin. Our maintained plugins are documented in the following locations: