Federation Reference

This page provides a reference on all the fields you can set when defining federation parameters, and describes how you can monitor federation links.

Configuration reference

Policies

A policy can apply an upstream set (including the implicitly-defined upstream set “all”) or a single upstream to a set of exchanges and / or queues.

To apply all upstreams:

rabbitmqctl set_policy federate-me '^amq\.' '{"federation-upstream-set":"all"}'

To apply a named set of upstreams:

rabbitmqctl set_policy federate-me '^amq\.' '{"federation-upstream-set":"my-set"}'

To apply a single upstream:

rabbitmqctl set_policy federate-me '^amq\.' '{"federation-upstream":"my-upstream"}'

Note that you cannot use the federation-upstream and federation-upstream-set keys together in a policy. For more detail on policies, see the policy documentation.

Upstreams

A federation-upstream parameter specifies how to connect to a broker. It takes the form:

rabbitmqctl set_parameter federation-upstream name 'json-object'

The json-object can contain the following keys:

Applying to federated exchanges and federated queues

uri
The AMQP URI(s) for the upstream. Mandatory. See the AMQP URI reference for information on how RabbitMQ treats AMQP URIs in general, and the query parameter reference for the Erlang client’s extensions (including those for SSL and SASL) which are available to federation.

Note that this field can either be a string, or a list of strings. If more than one string is provided, the federation plugin will randomly pick one URI from the list. This can be used to connect to an upstream cluster and ensure the link will eventually find another node in the event that one fails. It’s probably not a great idea to use multiple URIs that do not point to the same cluster.

To connect to multiple URIs simultaneously use multiple upstreams.

prefetch-count
The maximum number of unacknowledged messages copied over a link at any one time. Default is 1000.

reconnect-delay
The duration (in seconds) to wait before reconnecting to the broker after being disconnected. Default is 1.

ack-mode
Determines how the link should acknowledge messages. If set to on-confirm (the default), messages are acknowledged to the upstream broker after they have been confirmed downstream. This handles network errors and broker failures without losing messages, and is the slowest option.

If set to on-publish, messages are acknowledged to the upstream broker after they have been published downstream. This handles network errors without losing messages, but may lose messages in the event of broker failures.

If set to no-ack, message acknowledgements are not used. This is the fastest option, but may lose messages in the event of network or broker failures.

trust-user-id
Determines how federation should interact with the validated user-id feature. If set to true, federation will pass through any validated user-id from the upstream, even though it cannot validate it itself. If set to false or not set, it will clear any validated user-id it encounters. You should only set this to true if you trust the upstream server (and by extension, all its upstreams) not to forge user-ids.

Applying to federated exchanges only

exchange
The name of the upstream exchange. Default is to use the same name as the federated exchange.

max-hops
The maximum number of federation links that a message published to a federated exchange can traverse before it is discarded. Default is 1. Note that even if max-hops is set to a value greater than 1, messages will never visit the same node twice due to travelling in a loop. However, messages may still be duplicated if it is possible for them to travel from the source to the destination via multiple routes.

expires
The expiry time (in milliseconds) after which an upstream queue for a federated exchange may be deleted, if a connection to the upstream broker is lost. The default is ‘none’, meaning the queue should never expire.

This setting controls how long the upstream queue will last before it is eligible for deletion if the connection is lost.

This value is used to set the “x-expires” argument for the upstream queue.

message-ttl
The expiry time for messages in the upstream queue for a federated exchange (see expires), in milliseconds. Default is 'none’, meaning messages should never expire. This does not apply to federated queues.

This value is used to set the “x-message-ttl” argument for the upstream queue.

ha-policy
Determines the “x-ha-policy” argument for the upstream queue for a federated exchange (see expires). This is only of interest when connecting to old brokers which determine queue HA mode using this argument. Default is 'none’, meaning the queue is not HA.

Applying to federated queues only

queue
The name of the upstream queue. Default is to use the same name as the federated queue.

Upstream sets

Each upstream-set list is a set of upstreams.

rabbitmqctl set_parameter federation-upstream-set name '[json-object, json-object, ...]'

The keys of the JSON objects can be:

upstream
The name of an upstream. Mandatory.

In addition, any of the properties from an upstream can be overridden in an upstream set.

There is an implicitly-defined upstream set, all, which contains all upstreams.

cluster name

The federation plugin uses the cluster name defined within the server to identify itself to other nodes in the federation graph. (The default is constructed from the Erlang node and the fully-qualified domain name of the first node to form the cluster.)

This can be changed with rabbitmqctl set_cluster_name or via the management plugin.

It is important to specify this explicitly if your DNS will not give machines distinct names.

Example:

rabbitmqctl set_cluster_name '"my-name"'

Each combination of federated exchange or queue and upstream needs a link to run. This is the process that retrieves messages from upstream and republishes them downstream. You can monitor the status of federation links using rabbitmqctl and the management plugin.

Using rabbitmqctl

Invoke:

rabbitmqctl eval 'rabbit_federation_status:status().'

This will return a list of federation links running on the node you are connecting to (i.e. not cluster-wide). It contains the following keys:

type
exchange or queue depending on what type of federated object this link relates to

name
the name of the federated exchange or queue

upstream_name
the name of the upstream exchange or queue

vhost
the virtual host containing the federated exchange or queue

connection
the name of the connection for this link (from config)

status
status of the link:

  • starting
  • {running, LocalConnectionName}
  • {shutdown, Error}

timestamp
time the status was last updated

Example:

# rabbitmqctl eval 'rabbit_federation_status:status().'
[[{type,<<"exchange">>},
  {name,<<"my-exchange">>},
  {vhost,<<"/">>},
  {connection,<<"upstream-server">>},
  {upstream_name,<<"my-upstream-x">>},
  {status,{running,<<"<rabbit@<example>.1.281.0>">>}},
  {timestamp,{{2012,3,1},{12,3,28}}}]]
...done.

Using the management plugin

Install the rabbitmq_federation_management plugin. You will now be able to see all federation links in the cluster by clicking on Admin > Federation Status, or making an HTTP request to GET /api/federation-links.