https://www.rabbitmq.com/assets/js/b1764732.2dacf694.js

1"use strict";(self.webpackChunkrabbitmq_website=self.webpackChunkrabbitmq_website||[]).push([["16604"],{85556(e,n,t){t.r(n),t.d(n,{metadata:()=>s,default:()=>h,frontMatter:()=>a,contentTitle:()=>d,toc:()=>o,assets:()=>l});var s=JSON.parse('{"id":"federation-reference","title":"Federation Reference","description":"\x3c!--","source":"@site/versioned_docs/version-4.2/federation-reference.md","sourceDirName":".","slug":"/federation-reference","permalink":"/docs/4.2/federation-reference","draft":false,"unlisted":false,"editUrl":"https://github.com/rabbitmq/rabbitmq-website/tree/main/versioned_docs/version-4.2/federation-reference.md","tags":[],"version":"4.2","frontMatter":{"title":"Federation Reference"},"sidebar":"docsSidebar","previous":{"title":"Federated Exchanges","permalink":"/docs/4.2/federated-exchanges/"},"next":{"title":"Shovel Plugin","permalink":"/docs/4.2/shovel"}}'),r=t(74848),i=t(28453);let a={title:"Federation Reference"},d="Federation Reference",l={},o=[{value:"Overview",id:"overview",level:2},{value:"Configuration Reference",id:"configuration",level:2},{value:"Policies",id:"policies",level:3},{value:"Upstreams",id:"upstreams",level:3},{value:"Applicable to Both Federated Exchanges and Queues",id:"applicable-to-both-federated-exchanges-and-queues",level:4},{value:"Applying to Federated Exchanges Only",id:"applying-to-federated-exchanges-only",level:4},{value:"Applicable to Federated Queues Only",id:"applicable-to-federated-queues-only",level:4},{value:"Upstream Sets",id:"upstream-sets",level:2},{value:"cluster name",id:"cluster-name",level:2}];function c(e){let n={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",h4:"h4",header:"header",p:"p",pre:"pre",...(0,i.R)(),...e.components};return(0,r.jsxs)(r.Fragment,{children:[(0,r.jsx)(n.header,{children:(0,r.jsx)(n.h1,{id:"federation-reference",children:"Federation Reference"})}),"\n",(0,r.jsx)(n.h2,{id:"overview",children:"Overview"}),"\n",(0,r.jsxs)(n.p,{children:["This guides provides a reference on all the fields that can be set\nwhen defining various parameters related to ",(0,r.jsx)(n.a,{href:"./federation",children:"federation"}),"."]}),"\n",(0,r.jsxs)(n.p,{children:["Please refer to ",(0,r.jsx)(n.a,{href:"./federation",children:"other federation-related guides"})," to learn about the concepts\nand how to get started."]}),"\n",(0,r.jsx)(n.h2,{id:"configuration",children:"Configuration Reference"}),"\n",(0,r.jsx)(n.h3,{id:"policies",children:"Policies"}),"\n",(0,r.jsx)(n.p,{children:'A policy can apply an upstream set (including the\nimplicitly-defined upstream set named "all") or a single upstream\nto a set of exchanges and/or queues.'}),"\n",(0,r.jsx)(n.p,{children:"To apply all upstreams:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"rabbitmqctl set_policy federate-me '^federated\\.' '{\"federation-upstream-set\":\"all\"}'\n"})}),"\n",(0,r.jsx)(n.p,{children:"To apply a named set of upstreams:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:'rabbitmqctl set_parameter federation-upstream-set location-1 \'[{"upstream": "up-1"}, {"upstream": "up-2"}]\'\n\nrabbitmqctl set_policy federate-me \'^federated\\.\' \'{"federation-upstream-set":"location-1"}\'\n'})}),"\n",(0,r.jsx)(n.p,{children:"To apply a single upstream:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"rabbitmqctl set_policy federate-me '^federated\\.' '{\"federation-upstream\":\"up-1\"}'\n"})}),"\n",(0,r.jsxs)(n.p,{children:["Note that you cannot use the ",(0,r.jsx)("code",{children:"federation-upstream"}),"\nand ",(0,r.jsx)("code",{children:"federation-upstream-set"})," keys together in a\npolicy. For more detail on policies, see the ",(0,r.jsx)("a",{href:"/policies",children:"policy"})," documentation."]}),"\n",(0,r.jsx)(n.h3,{id:"upstreams",children:"Upstreams"}),"\n",(0,r.jsxs)(n.p,{children:["A ",(0,r.jsx)("code",{children:"federation-upstream"})," parameter specifies how\nto connect to a remote node or cluster as well as certain properties\nof a link (connection). Upstreams are defined using the\n",(0,r.jsx)(n.code,{children:"rabbitmqctl set_parameter federation-upstream"})," command which accepts\nan upstream name and an upstream definition JSON object:"]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:"rabbitmqctl set_parameter federation-upstream 'name' 'json-object'\n"})}),"\n",(0,r.jsx)(n.p,{children:"The upstream definition object can contain the following keys:"}),"\n",(0,r.jsx)(n.h4,{id:"applicable-to-both-federated-exchanges-and-queues",children:"Applicable to Both Federated Exchanges and Queues"}),"\n",(0,r.jsxs)("table",{children:[(0,r.jsx)("thead",{children:(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{children:"Parameter Name"}),(0,r.jsx)("td",{children:"Description"})]})}),(0,r.jsxs)("tbody",{children:[(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{children:(0,r.jsx)("code",{children:"uri"})}),(0,r.jsxs)("td",{children:[(0,r.jsxs)(n.p,{children:["The  ",(0,r.jsx)("a",{href:"./uri-spec",children:"AMQP URI(s)"})," for the upstream.\nSee the ",(0,r.jsx)("a",{href:"./uri-query-parameters",children:"query parameter reference"})," for the underlying client library extensions\n(including those for ",(0,r.jsx)("a",{href:"./ssl",children:"TLS"}),") which are available to federation."]}),(0,r.jsxs)(n.p,{children:["A URI that does not include credentials connects as the default user (",(0,r.jsx)("code",{children:"guest"}),"),\nwhose connectivity is ",(0,r.jsxs)("a",{href:"./access-control#loopback-users",children:["restricted to ",(0,r.jsx)(n.code,{children:"localhost"})]}),"."]}),(0,r.jsxs)(n.p,{children:["In production environments, the default user ",(0,r.jsx)("a",{href:"./production-checklist#users",children:"should use a generated username and password"}),",\nor deleted entirely in favor of a manually created user."]}),(0,r.jsxs)(n.p,{children:["The value can either be a string, or a list of\

1nstrings. If more than one string is provided, the federation\nplugin will randomly pick ",(0,r.jsx)("b",{children:"one"})," URI from the list when attempting to connect. This can\nbe used to connect to an upstream cluster and ensure the link\nwill eventually find another node in the event that one fails.\nAll URIs are assumed to be pointed at nodes in a single cluster.\nTo connect to multiple endpoints in separate clusters simultaneously use multiple upstreams."]})]})]}),(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{children:(0,r.jsx)("code",{children:"prefetch-count"})}),(0,r.jsx)("td",{children:(0,r.jsxs)(n.p,{children:["The ",(0,r.jsx)("a",{href:"./confirms",children:"maximum number of deliveries pending acknowledgement"})," on a link at\nany given time. Default is ",(0,r.jsx)("code",{children:"1000"}),". Increasing this value can improve link\nthroughput up to a point but will also result in higher memory usage of the link."]})})]}),(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{children:(0,r.jsx)("code",{children:"reconnect-delay"})}),(0,r.jsx)("td",{children:(0,r.jsx)(n.p,{children:"The duration (in seconds) to wait before reconnecting to the broker\nafter being disconnected. Default is 1."})})]}),(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{children:(0,r.jsx)("code",{children:"ack-mode"})}),(0,r.jsxs)("td",{children:[(0,r.jsxs)(n.p,{children:["Determines how the link should acknowledge messages. If set\nto ",(0,r.jsx)("code",{children:"on-confirm"})," (the default), messages are\nacknowledged to the upstream broker after they have been\nconfirmed downstream. This handles network errors and broker\nfailures without losing messages, and is the slowest option."]}),(0,r.jsxs)(n.p,{children:["If set to ",(0,r.jsx)("code",{children:"on-publish"}),", messages are acknowledged to\nthe upstream broker after they have been published\ndownstream. This may lose messages in the event of network or broker failures."]}),(0,r.jsxs)(n.p,{children:["If set to ",(0,r.jsx)("code",{children:"no-ack"}),", message acknowledgements are not\nused. This is the fastest option, but may lose messages in the\nevent of network or broker failures."]})]})]}),(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{children:(0,r.jsx)("code",{children:"trust-user-id"})}),(0,r.jsx)("td",{children:(0,r.jsxs)(n.p,{children:["Determines how federation should interact with\nthe ",(0,r.jsx)("a",{href:"./validated-user-id",children:"validated user-id"})," feature.\nIf set to ",(0,r.jsx)("code",{children:"true"}),", federation will pass through any validated user-id from\nthe upstream, even though it cannot validate it itself.\nIf set to ",(0,r.jsx)("code",{children:"false"})," or not set, it will\nclear any validated user-id it encounters. You should\nonly set this to ",(0,r.jsx)("code",{children:"true"})," if you trust the\nupstream server (and by extension, all its upstreams)\nnot to forge user-ids."]})})]})]})]}),"\n",(0,r.jsx)(n.h4,{id:"applying-to-federated-exchanges-only",children:"Applying to Federated Exchanges Only"}),"\n",(0,r.jsxs)(n.p,{children:["The following upstream parameters are only applicable to ",(0,r.jsx)("a",{href:"./federated-exchanges",children:"federated exchanges"}),"."]}),"\n",(0,r.jsxs)("table",{children:[(0,r.jsx)("thead",{children:(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{children:"Parameter Name"}),(0,r.jsx)("td",{children:"Description"})]})}),(0,r.jsxs)("tbody",{children:[(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{children:(0,r.jsx)("code",{children:"exchange"})}),(0,r.jsx)("td",{children:(0,r.jsx)(n.p,{children:"The name of the upstream exchange. Default is to use the\nsame name as the federated exchange."})})]}),(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{children:(0,r.jsx)("code",{children:"max-hops"})}),(0,r.jsx)("td",{children:(0,r.jsxs)(n.p,{children:["The maximum number of federation links that a message\npublished to a federated exchange can traverse before it\nis discarded. Default is 1. Note that even if\n",(0,r.jsx)("code",{children:"max-hops"})," is set to a value greater than 1,\nmessages will never visit the same node twice due to\ntravelling in a loop. However, messages may still be\nduplicated if it is possible for them to travel from the\nsource to the destination via multiple routes."]})})]}),(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{children:(0,r.jsx)(n.code,{children:"queue-type"})}),(0,r.jsxs)("td",{children:[(0,r.jsxs)(n.p,{children:["The queue type of the ",(0,r.jsx)(n.a,{href:"./federated-exchanges#details",children:"internal upstream queue"})," used by exchange federation."]}),(0,r.jsxs)(n.p,{children:["Defaults to ",(0,r.jsx)(n.code,{children:"classic"})," (a single replica queue type). Set to ",(0,r.jsx)(n.code,{children:"quorum"})," to use a ",(0,r.jsx)(n.a,{href:"./quorum-queues",children:"replicated queue type"}),"."]}),(0,r.jsxs)(n.p,{children:["Changing the queue type will delete and recreate the upstream queue by default.\nThis may lead to messages getting lost or not routed anyw

1here during the re-declaration.\nTo avoid that, set ",(0,r.jsx)(n.code,{children:"resource-cleanup-mode"})," key to ",(0,r.jsx)(n.code,{children:"never"}),".\nThis requires manually deleting the old upstream queue so that it can be recreated with\nthe new type."]}),(0,r.jsxs)(n.p,{children:["Available since: ",(0,r.jsx)(n.code,{children:"3.13.1"})]})]})]}),(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{children:(0,r.jsx)(n.code,{children:"resource-cleanup-mode"})}),(0,r.jsxs)("td",{children:[(0,r.jsxs)(n.p,{children:["Whether to delete the ",(0,r.jsx)(n.a,{href:"./federated-exchanges#details",children:"internal upstream queue"})," when federation links stop."]}),(0,r.jsxs)(n.p,{children:["By default, the internal upstream queue is deleted immediately when a federation link stops.\nSet to ",(0,r.jsx)(n.code,{children:"never"})," to keep the upstream queue around and collect messages even when\nchanging federation configuration."]}),(0,r.jsx)(n.admonition,{type:"tip",children:(0,r.jsxs)(n.p,{children:["In the absense of inbound federation links, internal queues will continue accumulating messages until the node runs ",(0,r.jsx)(n.a,{href:"./alarms",children:"out of disk space"}),".\nTherefore this option should be used with a ",(0,r.jsx)(n.a,{href:"./maxlength",children:"length limit"})," defined via a policy and/or the ",(0,r.jsx)(n.code,{children:"message-ttl"})," setting with a reasonable value\n(say, 8-12 hours)."]})})]})]}),(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{children:(0,r.jsx)("code",{children:"expires"})}),(0,r.jsxs)("td",{children:[(0,r.jsxs)(n.p,{children:["The expiry time (in milliseconds) after which\nan ",(0,r.jsx)("a",{href:"./federated-exchanges#details",children:"upstream queue"})," for\na federated exchange may be deleted if a connection to the upstream is lost.\nThe default is ",(0,r.jsx)("code",{children:"'none'"}),", meaning no expiration will be applied to the queue."]}),(0,r.jsx)(n.p,{children:"This setting controls how long the upstream queue will\nlast before it is eligible for deletion if the connection is lost."}),(0,r.jsxs)(n.p,{children:["This value controls ",(0,r.jsx)("a",{href:"./ttl",children:"TTL settings"})," for the upstream queue."]})]})]}),(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{children:(0,r.jsx)("code",{children:"message-ttl"})}),(0,r.jsxs)("td",{children:[(0,r.jsxs)(n.p,{children:["The expiry time for messages in the ",(0,r.jsx)("a",{href:"./federated-exchanges#details",children:"upstream queue"}),"\nfor a federated exchange (see ",(0,r.jsx)("code",{children:"expires"}),"), in milliseconds.\nDefault is ",(0,r.jsx)("code",{children:"'none'"}),", meaning messages should never expire.\nThis does not apply to federated queues."]}),(0,r.jsxs)(n.p,{children:["This value controls ",(0,r.jsx)("a",{href:"./ttl",children:"TTL settings"})," for the messages in the upstream queue."]})]})]})]})]}),"\n",(0,r.jsx)(n.h4,{id:"applicable-to-federated-queues-only",children:"Applicable to Federated Queues Only"}),"\n",(0,r.jsxs)("table",{children:[(0,r.jsx)("thead",{children:(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{children:"Parameter Name"}),(0,r.jsx)("td",{children:"Description"})]})}),(0,r.jsxs)("tbody",{children:[(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{children:(0,r.jsx)("code",{children:"queue"})}),(0,r.jsx)("td",{children:(0,r.jsx)(n.p,{children:"The name of the upstream queue. Default is to use the same\nname as the federated queue."})})]}),(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{children:(0,r.jsx)("code",{children:"consumer-tag"})}),(0,r.jsx)("td",{children:(0,r.jsx)(n.p,{children:"The consumer tag to use when consuming from upstream. Optional."})})]})]})]}),"\n",(0,r.jsx)(n.h2,{id:"upstream-sets",children:"Upstream Sets"}),"\n",(0,r.jsxs)(n.p,{children:["Each ",(0,r.jsx)("code",{children:"upstream-set"})," is a set of upstreams. It can be more convenient to use a set\nand refer to it in a federation policy definition that repeatedly listing upstreams."]}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:'# up-1 and up-2 are previously declared upstream

1s\nrabbitmqctl set_parameter federation-upstream-set location-1 \'[{"upstream": "up-1"}, {"upstream": "up-2"}]\'\n'})}),"\n",(0,r.jsx)(n.p,{children:"Supported keys of the JSON objects are"}),"\n",(0,r.jsxs)("table",{children:[(0,r.jsx)("thead",{children:(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{children:"Parameter Name"}),(0,r.jsx)("td",{children:"Description"})]})}),(0,r.jsx)("tbody",{children:(0,r.jsxs)("tr",{children:[(0,r.jsx)("td",{children:(0,r.jsx)("code",{children:"upstream"})}),(0,r.jsx)("td",{children:(0,r.jsx)(n.p,{children:"The name of an upstream. Mandatory."})})]})})]}),"\n",(0,r.jsx)(n.p,{children:"In addition, any of the properties from an upstream can be\noverridden in an upstream set."}),"\n",(0,r.jsxs)(n.p,{children:["There is an implicitly-defined upstream set, ",(0,r.jsx)("code",{children:"all"}),",\nwhich contains all upstreams created in the target virtual host."]}),"\n",(0,r.jsx)(n.h2,{id:"cluster-name",children:"cluster name"}),"\n",(0,r.jsx)(n.p,{children:"The federation plugin uses the cluster name defined within the server\nto identify itself to other nodes in the federation graph.\nThe default is constructed from the RabbitMQ node name and\nthe fully-qualified domain name of the first node to form the cluster."}),"\n",(0,r.jsx)(n.p,{children:"This can be changed with the"}),"\n",(0,r.jsx)("code",{children:"rabbitmqctl set_cluster_name"}),"\n",(0,r.jsx)(n.p,{children:"command or via the management UI."}),"\n",(0,r.jsx)(n.p,{children:"It is important to specify this explicitly if your DNS will\nnot give machines distinct names."}),"\n",(0,r.jsx)(n.p,{children:"Here's an Example:"}),"\n",(0,r.jsx)(n.pre,{children:(0,r.jsx)(n.code,{className:"language-bash",children:'rabbitmqctl set_cluster_name "east1-production"\n'})})]})}function h(e={}){let{wrapper:n}={...(0,i.R)(),...e.components};return n?(0,r.jsx)(n,{...e,children:(0,r.jsx)(c,{...e})}):c(e)}},28453(e,n,t){t.d(n,{R:()=>a,x:()=>d});var s=t(96540);let r={},i=s.createContext(r);function a(e){let n=s.useContext(i);return s.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function d(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(r):e.components||r:a(e.components),s.createElement(i.Provider,{value:n},e.children)}}}]);