Virtual Hosts

RabbitMQ

Features
Get Started
Support
Community
Docs
Blog

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 and deleted 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.
Creating a Virtual Hosts

A virtual host can be created using CLI tools or an HTTP API endpoint.

A newly created vhost will have a default set of exchanges but no other entities and no user permissions. For a user to be able to connect and use the virtual host, permissions to it must be granted to every user that will use the vhost, e.g. using rabbitmqctl set_permissions.
Using CLI Tools

A virtual host can be created using rabbitmqctl’s add_vhost command which accepts virtual host name as the only mandatory argument.

Here’s an example that creates a virtual host named qa1:

rabbitmqctl add_vhost qa1

Using HTTP API

A virtual host can be created using the PUT /api/vhosts/{name} HTTP API endpoint where {name} is the name of the virtual host

Here’s an example that uses curl to create a virtual host vh1 by contacting a node at rabbitmq.local:15672:

curl -u userename:pa$sw0rD -X PUT http://rabbitmq.local:15672/api/vhosts/vh1

Bulk Creation and Pre-provisioning

Virtual host creation involves a blocking cluster-wide transaction. Each node has to perform a number of setup steps which are moderately expensive. In practice it can take up to a few seconds for a virtual host to be created.

When a number of virtual hosts is created in a loop, CLI and HTTP API clients can outpace the actual rate of virtual host creation and experience timeouts. If that’s the case operation timeout should be increased and delays should be introduced between operations.

Definition export and import is the recommended way of pre-configuring many virtual hosts at deployment time.
Deleting a Virtual Hosts

A virtual host can be created using CLI tools or an HTTP API endpoint.

Deleting a virtual host will permanently delete all entities (queues, exchanges, bindings, policies, permissions, etc) in it.
Using CLI Tools

A virtual host can be deleted using rabbitmqctl’s delete_vhost command which accepts virtual host name as the only mandatory argument.

Here’s an example that deletes a virtual host named qa1:

rabbitmqctl delete_vhost qa1

Using HTTP API

A virtual host can be deleted using the DELETE /api/vhosts/{name} HTTP API endpoint where {name} is the name of the virtual host

Here’s an example that uses curl to delete a virtual host vh1 by contacting a node at rabbitmq.local:15672:

curl -u userename:pa$sw0rD -X DELETE http://rabbitmq.local:15672/api/vhosts/vh1

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 ❤️

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!
In This Section

Server Documentation
    Configuration
    Management UI
    Monitoring
    Production Checklist
    TLS Support
    Feature Flags
    Distributed RabbitMQ
    Clustering
    Reliable Delivery
    Backup and restore
    Alarms
    Memory Use
    Networking
    Virtual Hosts
    High Availability (pacemaker)
    Access Control (Authorisation)
    Authentication Mechanisms
    LDAP
    Lazy Queues
    Internal Event Exchange
    Firehose (Message Tracing)
    Manual Pages
    Windows Quirks
Client Documentation
Plugins
News
Protocol
Our Extensions
Building
Previous Releases
License

RabbitMQ

Features
Get Started
Support
Community
Docs
Blog

Copyright © 2007-2020 VMware, Inc. or its affiliates. All rights reserved. Terms of Use, Privacy and Trademark Guidelines