RabbitMQ


This is the RabbitMQ Server Administrator's Guide. (Note: it is still under development. Please contact us if you have any suggestions or wished-for features!)

See also this list of new community tools have appeared for 'dashboard' access to core management functionality.

Building and installation

Please see the build and installation guides for instructions on compiling, installing, starting and shutting down the server. See the service guide for instructions on running the server as a Windows Service.

Default database contents

When the server first starts running, and detects that its database is uninitialised or has been deleted, it initialises a fresh database with the following resources:

  • a virtual host named /
  • a user named guest with a default password of guest, granted full access to the / virtual host.

It is advisable to change the password of the guest user to something private, particularly if your broker is accessible publicly.

Management

rabbitmqctl is a command line tool for managing a RabbitMQ broker. For (much) more information on rabbitmqctl, please see the rabbitmqctl(1) man page.

Access control

When an AMQP client establishes a connection to an AMQP server, it specifies a virtual host within which it intends to operate. A first level of access control is enforced at this point, with the server checking whether the user has any permissions to access the virtual hosts, and rejecting the connection attempt otherwise.

Resources, i.e. exchanges and queues, are named entities inside a particular virtual host; the same name denotes a different resource in each virtual host. A second level of access control is enforced when certain operations are performed on resources.

RabbitMQ distinguishes between configure, write and read operations on a resource. The configure operations create or destroy resources, or alter their behaviour. The write operations inject messages into a resource. And the read operations retrieve messages from a resource.

In order to perform an operation on a resource the user must have been granted the appropriate permissions for it. The following table shows what permissions on what type of resource are required for all the AMQP commands which perform permission checks.

AMQP command configure write read
exchange.declare exchange
exchange.delete exchange
queue.declare queue
queue.delete queue
queue.bind queue exchange
basic.publish exchange
basic.get queue
basic.consume queue
queue.purge queue

Permissions are expressed as a triple of regular expressions - one each for configure, write and read - on per-vhost basis. The user is granted the respective permission for operations on all resources with names matching the regular expressions. (Note: For convenience RabbitMQ maps AMQP's default exchange's blank name to 'amq.default' when performing permission checks.)

Some AMQP operations can create resources with server-generated names. By default, every user has configure, write and read permissions for such resources. The names are strong and not discoverable as part of the protocol, only through management functionality. Therefore, these resources are in effect private to the client that created them, unless their names are explicitly shared with other clients via some external mechanism.

Permissions have scope. Permissions with client scope are enforced only for client-specified names. As detailed above, operations with server-generated names are allowed. Permissions with all scope are enforced for all resources. In this case, users must be explicitly granted permission to 'amq\.gen.*' if they are to use server-generated resources. Similarly, grant no access could simply be expressed as ''. Permissions have client scope, by default.

NB. Due to a bug in RabbitMQ 2.0.0, all permissions are treated as having scope "all". This means that, in order for a client to use server generated names, it must explicitly be granted permission to 'amq\.gen.*'. Similarly, if a client intends to use the default exchange, it must be granted permission to 'amq\.default'.

The regular expression '^$', i.e. matching nothing but the empty string, exactly covers resources with server-generated names. That, for example, allows an administrator to restrict a user to declaring private resources only. The empty string, '' is a synonym for '^$' and restricts permissions in the exact same way.

RabbitMQ may cache the results of access control checks on a per-connection or per-channel basis. Hence changes to user permissions may only take effect when the user reconnects.

For details of how to set up access control, please see the Access Control section of the rabbitmqctl(1) man page.

Plugins

RabbitMQ provides a plugin mechanism allowing for additional OTP applications to be run within the broker node. Plugins should not be seen as a general purpose mechanism for writing applications, but instead as a specialised tool when additional functionality is required at the broker level.

The RabbitMQ plugin mechanism makes use of a custom OTP .boot file, to start additional OTP applications within the broker node, and thus comes with a number of caveats:

  • Since the plugin runs in the same node as the broker, it should not be assumed that any access controls configured on the broker will be observed by the plugin. Whilst plugins can interact with the ACL mechanism to ensure enforcement of security mechanisms, it is also possible for plugins to completely ignore security configuration.
  • Again, since the plugin runs in the same node as the broker, an action that results in the node halting will shut down the RabbitMQ broker as well. Well-written plugins can be built to avoid this occuring, however Administrators should be aware of the risks of installing plugins - especially those that are not known to have undergone a rigorous QA procedure.

Plugin Installation

  • Plugins will generally be available in two forms. The expected form for a packaged plugin will be a .ez erlang archive. Alternatively, more developmental plugins may be distributed directly from source control, whereby they will be a directory containing (at least) an ebin subdirectory.
  • In both cases, the plugin archive (or directory) should be placed into the plugins subdirectory within the rabbitmq-server installation directory (ie, the directory that the ebin directory resides within). If this directory does not exist, it can be safely created.
  • After adding new plugins to the plugins subdirectory, restart the RabbitMQ server. As it starts, it scans the plugins subdirectory and activates all the plugins it finds there automatically before continuing to load.
  • Note for users with RabbitMQ installed as a Windows Service: Each time you add plugins to the plugins directory, you must re-run the
    rabbitmq-service.bat install
    command to ensure that the service configuration is updated to perform an appropriate boot sequence.

Plugin Un-installation

To remove an installed plugin from the broker, delete the .ez file or directory from the plugins directory. When the broker is restarted, the deleted plugin will no longer be started.

Note for users with RabbitMQ installed as a Windows Service: Just as for installation, every time you remove plugins from the plugins directory, you must re-run the

rabbitmq-service.bat install
command to ensure that the service configuration is updated to perform an appropriate boot sequence.

Disabling all Plugins

In the event of broker mis-behaviour, it is recommended that all plugins be disabled as a first port-of-call. Either move the plugins subdirectory away, or delete it. When Rabbit is restarted, no custom plugins will be loaded.