Federation Reference


This guides provides a reference on all the fields that can be set when defining various parameters related to federation.

Please refer to other federation-related guides to learn about the concepts and how to get started.

Configuration Reference


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

To apply all upstreams:

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

To apply a named set of upstreams:

rabbitmqctl set_parameter federation-upstream-set location-1 '[{"upstream": "up-1"}, {"upstream": "up-2"}]'

rabbitmqctl set_policy federate-me '^federated\.' '{"federation-upstream-set":"location-1"}'

To apply a single upstream:

rabbitmqctl set_policy federate-me '^federated\.' '{"federation-upstream":"up-1"}'

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.


A federation-upstream parameter specifies how to connect to a remote node or cluster as well as certain properties of a link (connection). Upstreams are defined using the rabbitmqctl set_parameter federation-upstream command which accepts an upstream name and an upstream definition JSON object:

rabbitmqctl set_parameter federation-upstream name 'json-object'

The upstream definition object can contain the following keys:

Applicable to Both Federated Exchanges and Queues

Parameter Name Description
uri The AMQP URI(s) for the upstream. See the query parameter reference for the underlying client library extensions (including those for TLS) which are available to federation.
    The value can either be a string, or a list of
    strings. If more than one string is provided, the federation
    plugin will randomly pick <b>one</b> URI from the list when attempting to connect. 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.
    All URIs are assumed to be pointed at nodes in a single cluster.
    To connect to multiple endpoints in separate clusters simultaneously use multiple upstreams.

    The <a href="./confirms.html">maximum number of deliveries pending acknowledgement</a> on a link at
    any given time. Default is <code>1000</code>. Increasing this value can improve link
    throughput up to a point but will also result in higher memory usage of the link.

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

    Determines how the link should acknowledge messages. If set
    to <code>on-confirm</code> (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 <code>on-publish</code>, 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 <code>no-ack</code>, message acknowledgements are not
    used. This is the fastest option, but may lose messages in the
    event of network or broker failures.

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

Applying to Federated Exchanges Only

The following upstream parameters are only applicable to federated exchanges.

    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
    <code>max-hops</code> 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.

    The expiry time (in milliseconds) after which
    an <a href="federated-exchanges.html#implementation">upstream queue</a> for
    a federated exchange may be deleted if a connection to the upstream is lost.
    The default is <code>'none'</code>, meaning no expiration will be applied to the queue.

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

    This value controls <a href="./ttl.html">TTL settings</a> for the upstream queue.

    The expiry time for messages in the <a href="federated-exchanges.html#implementation">upstream queue</a>
    for a federated exchange (see <code>expires</code>), in milliseconds.
    Default is <code>'none'</code>, meaning messages should never expire.
    This does not apply to federated queues.

    This value controls <a href="./ttl.html">TTL settings</a> for the messages in the upstream queue.
Parameter Name Description
exchange The name of the upstream exchange. Default is to use the same name as the federated exchange.

Applicable to Federated Queues Only

    The consumer tag to use when consuming from upstream. Optional.
Parameter Name Description
queue The name of the upstream queue. Default is to use the same name as the federated queue.

Upstream Sets

Each upstream-set is a set of upstreams. It can be more convenient to use a set and refer to it in a federation policy definition that repeatedly listing upstreams.

# up-1 and up-2 are previously declared upstreams
rabbitmqctl set_parameter federation-upstream-set location-1 '[{"upstream": "up-1"}, {"upstream": "up-2"}]'

Supported keys of the JSON objects are

Parameter Name Description
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 created in the target virtual host.

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 RabbitMQ node name and the fully-qualified domain name of the first node to form the cluster.

This can be changed with the

rabbitmqctl set_cluster_name

command or via the management UI.

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

Here's an Example:

rabbitmqctl set_cluster_name "east1-production"
check-circle-line exclamation-circle-line close-line
Scroll to top icon