File and Directory Locations
Overview
Every RabbitMQ node uses a number of files and directories to load configuration; store data, metadata, log files, and so on. Their location can be changed.
This guide covers:
- How to customise location of various directories and files used RabbitMQ nodes
- Default locations for various operating systems
- Other topics related to file and directory locations
This guide accompanies the main Configuration guide.
Overriding Locations
A number of environment variables specifies where RabbitMQ should locate certain things. In most environments default values should work just fine.
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![and]{}and}
The above characters will render the node unable to start or function as expected (e.g. expand plugins and load their metadata).
When changing file or directory locations, it is important to make sure that they have sufficient permissions for RabbitMQ node OS process to read and write from. It's best to assume that most directories and files used by RabbitMQ require read, write, and file creation permissions. Debian, RPM and Windows installer scripts will set up file system permissions suitable for most environments, however, when strict default permissions are used system-wide, it may be necessary to run additional configuration steps after installation to make sure RabbitMQ node file and directories have sufficient permissions
Environment Variables
| Name | Description |
|---|---|
| RABBITMQ_BASE | Note: Windows-specific. This base directory contains sub-directories for the RabbitMQ server's database and log files. Instead of overriding RABBITMQ_MNESIA_BASE and RABBITMQ_LOG_BASE individually, it may be easier to override the base directory instead. |
| RABBITMQ_CONFIG_FILE | The path to the configuration file, without the .config extension. If the configuration file is present it is used by the server to configure RabbitMQ components. See Configuration guide for more information. |
| 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. See Configuration guide for more information. |
| 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 RABBITMQ_MNESIA_DIR is overridden instead. |
| RABBITMQ_MNESIA_DIR | 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_SCHEMA_DIR | The directory where RabbitMQ keeps its configuration schema used by the new style configuration file. |
| RABBITMQ_LOG_BASE | This base directory contains the RabbitMQ server's log files, unless RABBITMQ_LOGS is set. |
| RABBITMQ_LOGS | The path of the RabbitMQ server's Erlang log file. This variable cannot be overridden on Windows. |
| RABBITMQ_PLUGINS_DIR | 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. |
| RABBITMQ_PLUGINS_EXPAND_DIR | Working directory used to expand enabled plugins when starting the server. It is important that effective RabbitMQ user has sufficient permissions to read and create files and subdirectories in this directory. |
| RABBITMQ_ENABLED_PLUGINS_FILE | This file records explicitly enabled plugins. When a plugin is enabled or disabled, this file will be recreated. It is important that effective RabbitMQ user has sufficient permissions to read, write and create this file at any time. |
| RABBITMQ_PID_FILE | File in which the process id is placed for use by rabbitmqctl wait. |
Default Locations on Linux, macOS, BSD
In the following table the ${install_prefix} to some paths is indicated. Homebrew installations use the installation-prefix (Homebrew Cellar) when installed. By default this is /usr/local.
Debian and RPM package installations use an empty ${install_prefix}.
| Name | Location |
|---|---|
| RABBITMQ_BASE | (Not used - Windows only) |
| RABBITMQ_CONFIG_FILE | ${install_prefix}/etc/rabbitmq/rabbitmq |
| RABBITMQ_MNESIA_BASE | ${install_prefix}/var/lib/rabbitmq/mnesia |
| RABBITMQ_MNESIA_DIR | $RABBITMQ_MNESIA_BASE/$RABBITMQ_NODENAME |
| RABBITMQ_LOG_BASE | ${install_prefix}/var/log/rabbitmq |
| RABBITMQ_LOGS | $RABBITMQ_LOG_BASE/$RABBITMQ_NODENAME.log |
| RABBITMQ_PLUGINS_DIR | /usr/lib/rabbitmq/plugins:$RABBITMQ_HOME/plugins Note that /usr/lib/rabbitmq/plugins is used only when RabbitMQ is installed into the standard (default) location. |
| RABBITMQ_PLUGINS_EXPAND_DIR | $RABBITMQ_MNESIA_BASE/$RABBITMQ_NODENAME-plugins-expand |
| RABBITMQ_ENABLED_PLUGINS_FILE | ${install_prefix}/etc/rabbitmq/enabled_plugins |
| RABBITMQ_PID_FILE | $RABBITMQ_MNESIA_DIR.pid |
Default Locations on Windows
| Name | Location |
|---|---|
| RABBITMQ_BASE | %APPDATA%\RabbitMQ |
| RABBITMQ_CONFIG_FILE | %RABBITMQ_BASE%\rabbitmq |
| RABBITMQ_MNESIA_BASE | %RABBITMQ_BASE%\db |
| RABBITMQ_MNESIA_DIR | %RABBITMQ_MNESIA_BASE%\%RABBITMQ_NODENAME%-mnesia |
| RABBITMQ_LOG_BASE | %RABBITMQ_BASE%\log |
| RABBITMQ_LOGS | %RABBITMQ_LOG_BASE%\%RABBITMQ_NODENAME%.log |
| RABBITMQ_PLUGINS_DIR | Installation-directory/plugins |
| RABBITMQ_PLUGINS_EXPAND_DIR | %RABBITMQ_MNESIA_BASE%\%RABBITMQ_NODENAME%-plugins-expand |
| RABBITMQ_ENABLED_PLUGINS_FILE | %RABBITMQ_BASE%\enabled_plugins |
| RABBITMQ_PID_FILE | (Not currently supported) |
Generic Binary Build Defaults
These are the defaults obtained when unpacking the Generic Unix tar-file and running the server without modification. In this table $RABBITMQ_HOME refers to the directory produced when extracting the archive.
| Name | Location |
|---|---|
| RABBITMQ_BASE | (Not used) |
| RABBITMQ_CONFIG_FILE | $RABBITMQ_HOME/etc/rabbitmq/rabbitmq |
| RABBITMQ_MNESIA_BASE | $RABBITMQ_HOME/var/lib/rabbitmq/mnesia |
| RABBITMQ_MNESIA_DIR | $RABBITMQ_MNESIA_BASE/$RABBITMQ_NODENAME |
| RABBITMQ_LOG_BASE | $RABBITMQ_HOME/var/log/rabbitmq |
| RABBITMQ_LOGS | $RABBITMQ_LOG_BASE/$RABBITMQ_NODENAME.log |
| RABBITMQ_PLUGINS_DIR | $RABBITMQ_HOME/plugins |
| RABBITMQ_PLUGINS_EXPAND_DIR | $RABBITMQ_MNESIA_BASE/$RABBITMQ_NODENAME-plugins-expand |
| RABBITMQ_PID_FILE | $RABBITMQ_MNESIA_DIR.pid |
