Skip to main content
Version: 3.13

Runtime Parameters

Overview​

While much of the configuration for RabbitMQ lives in the configuration file, some things do not mesh well with the use of a configuration file:

  • If they need to be the same across all nodes in a cluster
  • If they are likely to change at run time

RabbitMQ calls these items parameters. Parameters can be set by invoking rabbitmqctl or through the HTTP API.

There are two kinds of parameters: virtual host-scoped parameters and global parameters. The former, as the name suggests, are tied to a virtual host and consist of a component name, a name and a value.

For example, a dynamic shovel is definened using runtime parameters. It belongs to a virtual host, has a name and its component type is set to "shovel".

Global parameters are not tied to a particular virtual host and they consist of a name and value.

important

One important example of parameters usage is policies

Per-virtual host Parameters​

As stated above, there are vhost-scoped parameters and global parameters. An example of vhost-scoped parameter is a federation upstream: it targets a component (federation-upstream), it has a name that identifies it, it's tied to a virtual host (federation links will target some resources of this virtual host), and its value defines connection parameters to an upstream broker.

Virtual host-scoped parameters can be set, cleared and listed:

# sets a runtime parameter in a virtual host
rabbitmqctl set_parameter [-p vhost] <component_name> <name> <value>

# clears (unsets) a runtime parameter in a virtual host
rabbitmqctl clear_parameter [-p vhost] <component_name> <name>

# lists runtime parameters in a virtual host
rabbitmqctl list_parameters [-p vhost]

Global Parameters​

Global parameters is the other kind of parameters. An example of a global parameter is the name of the cluster. Global parameters can be set, cleared and listed:

# sets a global (virtual-host-independent) runtime parameter
rabbitmqctl set_global_parameter <name> <value>

# clears (unsets) a global (virtual-host-independent) runtime parameter
rabbitmqctl clear_global_parameter <name>

# lists global (virtual-host-independent) runtime parameters
rabbitmqctl list_global_parameters

Since a parameter value is a JSON document, you will usually need to quote it when creating one on the command line with rabbitmqctl. On Unix it is usually easiest to quote the whole document with single quotes, and use double quotes within it. On Windows you will have to escape every double quote. We give examples for both Unix and Windows for this reason.

Parameters reside in the database used by RabbitMQ for definitions of virtual hosts, exchanges, queues, bindings, users and permissions. Parameters are exported along with other object definitions by the management plugin's export feature.

Virtual-scoped parameters are used by the federation and shovel plugins.

Global parameters are used to store various cluster-level metadata, for example

Policies​

Policies are now documented in a dedicated guide.

Operator Policies​

Operator policies are now documented in the policies guide.