Parameters

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:

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

Parameters can be set, cleared and listed:

rabbitmqctl rabbitmqctl set_parameter {-p vhost} component_name name value
rabbitmqctl clear_parameter {-p vhost} component_name name
rabbitmqctl list_parameters {-p vhost}
HTTP API PUT /api/parameters/component_name/vhost/name
DELETE /api/parameters/component_name/vhost/name
GET /api/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.

Parameters are used by the federation and shovel plugins.

Policies

Policies automatically match against exchanges and queues, and help determine how they behave. Each exchange or queue will have at most one policy matching, and each policy then maps a set of key-value pairs on to the exchange or queue.

Policies therefore act somewhat like the arguments to exchange.declare and queue.declare, except that they are applied automatically without the involvement of the client application, and they can change at any time. Note that the set of features which can be controlled by policy is not the same as the set of features which can be controlled by arguments.

Policies are matched every time an exchange or queue is created, not just when the policy is created.

Policies can be used to configure the federation plugin, mirrored queues, alternate exchanges, dead lettering, per-queue TTLs, and maximum queue length.

An example of defining a policy looks like:

rabbitmqctl
rabbitmqctl set_policy federate-me "^amq\." '{"federation-upstream-set":"all"}' --priority 1 --apply-to exchanges
rabbitmqctl (Windows)
rabbitmqctl set_policy federate-me "^amq\." "{""federation-upstream-set"":""all""}" --priority 1 --apply-to exchanges
HTTP API
PUT /api/policies/%2f/federate-me
{"pattern": "^amq\.",
 "definition": {"federation-upstream-set":"all"},
 "priority": 1,
 "apply-to": "exchanges"}
Web UI
  • Navigate to Admin > Policies > Add / update a policy.
  • Enter "federate-me" next to Name, "^amq\." next to Pattern, and select "Exchanges" next to Apply to.
  • Enter "federation-upstream-set" = "all" in the first line next to Policy.
  • Click Add policy.

This matches the value "all" with the key "federation-upstream-set" for all exchanges with names beginning with "amq.", in the virtual host "/".

The "pattern" argument is a regular expression used to match exchange or queue names.

In the event that more than one policy can match a given exchange or queue, the policy with the greatest priority applies.

The "apply-to" argument can be "exchanges", "queues" or "all". The "apply-to" and "priority" settings are optional, in which case the defaults are "all" and "0" respectively.

Combining policy definitions

In some cases we might want to apply more than one policy definition to a resource. For example we might need a queue to be federated and mirrored. At most one policy will apply to a resource at any given time, but we can apply multiple definitions in that policy.

A federation policy definition would require an upstream set to be specified, so we would need the federation-upstream-set key in our definition. On the other hand to define some queues as mirrored, we would need the ha-mode key to be defined as well for the policy. Since the policy definition is just a JSON object, we can have both keys in the same policy definition.

Here's an example:

rabbitmqctl
rabbitmqctl set_policy ha-fed "^hf\." '{"federation-upstream-set":"all","ha-mode":"all"}' \
--priority 1 --apply-to queues
rabbitmqctl (Windows)
rabbitmqctl set_policy ha-fed "^hf\." "{""federation-upstream-set"":""all"", ""ha-mode"":""all""}" ^
--priority 1 --apply-to queues
HTTP API
PUT /api/policies/%2f/ha-fed
{"pattern": "^hf\.",
 "definition": {"federation-upstream-set":"all", "ha-mode": "all"},
 "priority": 1,
 "apply-to": "queues"}
Web UI
  • Navigate to Admin > Policies > Add / update a policy.
  • Enter "ha-fed" next to Name, "^hf\." next to Pattern, and select "Queues" next to Apply to.
  • Enter "federation-upstream-set" = "all" in the first line next to Policy.
  • Enter "ha-mode" = "all" on the next line.
  • Click Add policy.

By doing that all the queues matched by the pattern "^hf\." will have the "federation-upstream-set" and the "ha-mode" definitions applied to them.