Menu

Virtual Hosts

Introduction

RabbitMQ is multi-tenant system: connections, exchanges, queues, bindings, user permissions, policies and some other things belong to virtual hosts, logical groups of entities. If you are familiar with virtual hosts in Apache or server blocks in Nginx, the idea is similar. There is, however, one important difference: virtual hosts in Apache are defined in the configuration file; that's not the case with RabbitMQ: virtual hosts are created using rabbitmqctl or HTTP API instead.

Logical and Physical Separation

Virtual hosts provide logical grouping and separation of resources. Separation of physical resources is not a goal of virtual hosts and should be considered an implementation detail.

For example, resource permissions in RabbitMQ are scoped per virtual host. A user doesn't have global permissions, only permissions in one or more virtual hosts. User tags can be considered global permissions but they are an exception to the rule.

Therefore when talking about user permissions it is very Important to clarify what virtual host(s) they apply to.

Virtual Hosts and Client Connections

A virtual host has a name. When an AMQP 0-9-1 client connects to RabbitMQ, it specifies a vhost name to connect to. If authentication succeeds and the username provided was granted permissions to the vhost, connection is established.

Connections to a vhost can only operate on exchanges, queues, bindings, and so on in that vhost. "Interconnection" of e.g. a queue and an exchange in different vhosts is only possible when an application connects to two vhosts at the same time. For example, an application can consume from one vhost then republishes into the other. This scenario can involve vhosts in different clusters or the same cluster (or a single node). RabbitMQ Shovel plugin is one example of such application.

Virtual Hosts and STOMP

Like AMQP 0-9-1, STOMP includes the concept of virtual hosts. See the STOMP guide for details.

Virtual Hosts and MQTT

Unlike AMQP 0-9-1 and STOMP, MQTT doesn't have the concept of virtual hosts. MQTT connections use a single RabbitMQ host by default. There are MQTT-specific convention and features that make it possible for clients to connect to a specific vhosts without any client library modifications. See the MQTT guide for details.

Limits

In some cases it is desirable to limit the maximum allowed number of queues or concurrent client connections in a vhost. As of RabbitMQ 3.7.0, this is possible via per-vhost limits.

These limits can be configured using rabbitmqctl or HTTP API.

Configuring Limits Using rabbitmqctl

rabbitmqctl set_vhost_limits is the command used to define vhost limits. It requires a vhost parameter and a JSON document of limit definitions.

Configuring Max Connection Limit

To limit the total number of concurrent client connections in vhost vhost_name, use the following limit definition:

rabbitmqctl set_vhost_limits -p vhost_name '{"max-connections": 256}'

To disable client connections to a vhost, set the limit to a zero:

rabbitmqctl set_vhost_limits -p vhost_name '{"max-connections": 0}'

To lift the limit, set it to a negative value:

rabbitmqctl set_vhost_limits -p vhost_name '{"max-connections": -1}'

Configuring Max Number of Queues

To limit the total number of queues in vhost vhost_name, use the following limit definition:

rabbitmqctl set_vhost_limits -p vhost_name '{"max-queues": 1024}'

To lift the limit, set it to a negative value:

rabbitmqctl set_vhost_limits -p vhost_name '{"max-queues": -1}'

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!