https://www.rabbitmq.com/assets/js/2eb7e2fc.3ae6b4c2.js

1"use strict";(self.webpackChunkrabbitmq_website=self.webpackChunkrabbitmq_website||[]).push([["21122"],{84918(e,n,t){t.r(n),t.d(n,{metadata:()=>s,default:()=>l,frontMatter:()=>r,contentTitle:()=>a,toc:()=>h,assets:()=>d});var s=JSON.parse('{"id":"uri-spec","title":"RabbitMQ URI Specification","description":"\x3c!--","source":"@site/versioned_docs/version-4.0/uri-spec.md","sourceDirName":".","slug":"/uri-spec","permalink":"/docs/4.0/uri-spec","draft":false,"unlisted":false,"editUrl":"https://github.com/rabbitmq/rabbitmq-website/tree/main/versioned_docs/version-4.0/uri-spec.md","tags":[],"version":"4.0","frontMatter":{"title":"RabbitMQ URI Specification","displayed_sidebar":"docsSidebar"},"sidebar":"docsSidebar"}'),i=t(74848),o=t(28453);let r={title:"RabbitMQ URI Specification",displayed_sidebar:"docsSidebar"},a="RabbitMQ URI Specification",d={},h=[{value:"Overview",id:"overview",level:2},{value:"Introduction",id:"introduction",level:2},{value:"The "amqp" URI scheme",id:"the-amqp-uri-scheme",level:2},{value:"Host",id:"host",level:3},{value:"Port",id:"port",level:3},{value:"Username and password",id:"username-and-password",level:3},{value:"Virtual Host",id:"virtual-host",level:3},{value:"Handling of absent components",id:"handling-of-absent-components",level:2},{value:"The "amqps" URI scheme",id:"the-amqps-uri-scheme",level:2},{value:"Security Considerations",id:"security-considerations",level:2},{value:"Appendix A: Examples",id:"appendix-a-examples",level:2},{value:"Appendix B: Query parameters",id:"appendix-b-query-parameters",level:2}];function c(e){let n={code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",p:"p",pre:"pre",...(0,o.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.header,{children:(0,i.jsx)(n.h1,{id:"rabbitmq-uri-specification",children:"RabbitMQ URI Specification"})}),"\n",(0,i.jsx)(n.h2,{id:"overview",children:"Overview"}),"\n",(0,i.jsx)(n.p,{children:'This specification defines an "amqp" URI scheme. Conforming\nURIs represent the information needed by AMQP 0-9-1 clients\nas well as some RabbitMQ plugins to connect to RabbitMQ\nnodes.'}),"\n",(0,i.jsx)(n.h2,{id:"introduction",children:"Introduction"}),"\n",(0,i.jsx)(n.p,{children:"The scope of this\nspecification is limited to AMQP 0-9-1, the original protocol\nimplemented by RabbitMQ.  An AMQP 0-9-1 client connects\nto a RabbitMQ node in order to publish and consume messages\naccording to the messaging model."}),"\n",(0,i.jsx)(n.p,{children:"Several pieces of information are needed by a client to\nestablish and negotiate an AMQP 0-9-1 connection.\nThese connection parameters include:"}),"\n",(0,i.jsxs)("ul",{children:[(0,i.jsx)("li",{children:(0,i.jsx)(n.p,{children:"The parameters needed to establish the underlying TCP/IP\nconnection to the server (i.e. host address and port)."})}),(0,i.jsx)("li",{children:(0,i.jsxs)(n.p,{children:["Information to authenticate the client. AMQP 0-9-1 uses\n",(0,i.jsx)("a",{href:"http://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer",children:"SASL"}),"\nfor authentication.  Typically the ",(0,i.jsx)("code",{children:"PLAIN"})," mechanism is\nused, and so the authentication parameters consist of a\nusername and password."]})}),(0,i.jsx)("li",{children:(0,i.jsxs)(n.p,{children:['The name of the "virtual host" (or ',(0,i.jsx)("em",{children:"vhost"}),") that\nspecifies the namespace for entities (such as exchanges and queues)\nreferred to by the protocol. Note that this is not virtual\nhosting in the HTTP sense."]})})]}),"\n",(0,i.jsx)(n.p,{children:"A RabbitMQ client will typically obtain all these parameters\nfrom a configuration file or environment variables in order\nfor it to set up the connection. So it is convenient if the\nconnection parameters can be combined into a single\ncharacter string, rather than as distinct configuration\nsettings. That means that only one configuration setting is\nneeded, and only one value has to be passed to the client\nlibrary."}),"\n",(0,i.jsxs)(n.p,{children:["But combining the connection parameters into a single string\nrequires a convention, understood by the client\nlibrary, about exactly how the connection parameters are\nrepresented and delimited. It is desirable to standardise\nthat convention, so that it may be implemented consistently\nby many AMQP 0-9-1 client libraries. An obvious basis for such a\nstandard is the generic syntax for URIs defined in ",(0,i.jsx)("a",{href:"http://www.ietf.org/rfc/rfc3986.txt",children:"RFC3986"}),"."]}),"\n",(0,i.jsx)(n.p,{children:'The purpose of this specification is to define the "amqp"\nand "amqps" URI schemes which represent the AMQP 0-9-1\nconnection parameters within the generic URI syntax.'}),"\n",(0,i.jsx)(n.h2,{id:"the-amqp-uri-scheme",children:'The "amqp" URI scheme'}),"\n",(0,i.jsxs)(n.p,{children:["The syntax of an AMQP 0-9-1 URI is defined by the following ABNF\nrules.  All names in these rules not defined here are taken\nfrom ",(0,i.jsx)("a",{href:"http://www.ietf.org/rfc/rfc3986.txt",children:"RFC3986"}),"."]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{children:'amqp_URI       = "amqp://" amqp_authority [ "/" vhost ] [ "?" query ]\n\namqp_authority = [ amqp_userinfo "@" ] host [ ":" port ]\n\namqp_userinfo  = username [ ":" password ]\n\nusername       = *( unreserved / pct-encoded / sub-delims )\n\npassword       = *( unreserved / pct-encoded / sub-delims )\n\nvhost          = segment\n'})}),"\n",(0,i.jsx)(n.p,{children:"Once a URI has been successfully parsed according to this\nsyntax, the connection parameters are determined as\ndescribed 

1in the following sections."}),"\n",(0,i.jsx)(n.h3,{id:"host",children:"Host"}),"\n",(0,i.jsx)(n.p,{children:"The host to which the underlying TCP connection is made is\ndetermined from the host component according to RFC3986,\nsection 3.2.2.  Note that according to the ABNF, the host\ncomponent may not be absent, but it may be zero-length."}),"\n",(0,i.jsx)(n.h3,{id:"port",children:"Port"}),"\n",(0,i.jsx)(n.p,{children:'The port number to which the underlying TCP connection is\nmade is determined from the port component according to\nRFC3986.  The port component may be absent, indicated by the\nlack of the ":" character separating it from the host.  If\nit is absent, then the IANA-assigned port number for AMQP 0-9-1,\n5672, should be substituted instead.'}),"\n",(0,i.jsx)(n.h3,{id:"username-and-password",children:"Username and password"}),"\n",(0,i.jsxs)(n.p,{children:["If present, the username and password components should be\nused in the SASL exchange that occurs via the\n",(0,i.jsx)("code",{children:"connection.secure"})," and ",(0,i.jsx)("code",{children:"connection.secure-ok"})," AMQP 0-9-1 methods.\nAny percent-encoded octets in the username and password\nshould be decoded before they are used in the SASL exchange,\nand the resulting octet sequences should be regarded as\nUTF-8 encoded."]}),"\n",(0,i.jsx)(n.p,{children:'Both the username and password may be absent; their absence\nis indicated by the lack of the "@" character separating the\namqp_userinfo from the host.  If the username is present,\nthe password may be absent; this is indicated by the lack of\nthe ":" character separating it from the username.\nZero-length usernames and passwords are not equivalent to\nabsent usernames and passwords.'}),"\n",(0,i.jsx)(n.p,{children:'RFC3986 states that "A password appearing within the\nuserinfo component is deprecated and should be considered an\nerror" (section 7.5).  While this is sound advice in the\ncontext of user-facing applications (e.g. web browsers) and\nfor URIs that might be stored and displayed insecurely, it\nis not necessarily valid for backend applications.  Many of those\napplications are "headless" services, and open RabbitMQ connections on\nbehalf of the application as a whole rather than for\nspecific users. So the username and password identify the\napplication rather than a human user, and are likely to be\nincluded with connection parameters appearing in a secure\nstore of configuration settings. User-facing\napplications, which make RabbitMQ connections on behalf of\nspecific users, are also possible. In such cases the\nusername and password may be provided by the user to\nidentify themselves.  But such applications are the\nexception rather than the rule. Thus authors of\napplications implementing this specification should not\nconsider themselves bound by section 7.5 of RFC3986. Please\nalso see the section on "Security Considerations" below.'}),"\n",(0,i.jsx)(n.h3,{id:"virtual-host",children:"Virtual Host"}),"\n",(0,i.jsxs)(n.p,{children:["The virtual host (vhost) component is used as the basis for the\nvirtual-host field of the ",(0,i.jsx)("code",{children:"connection.open"})," AMQP 0-9-1 method.  Any\npercent-encoded octets in the vhost should be decoded before\nthe it is passed to the server."]}),"\n",(0,i.jsx)(n.p,{children:"Note that:"}),"\n",(0,i.jsxs)("ul",{children:[(0,i.jsx)("li",{children:'The vhost component of the URI does not include the\nleading "/" character from the path.  This makes it possible\nto refer to any vhost, not only those that begin with a "/"\ncharacter.'}),(0,i.jsx)("li",{children:'The vhost is a single segment.  Therefore, any "/"\ncharacters that appear in the vhost name must be\npercent-encoded. URIs with multi-segment paths do not obey\nthis specification.'})]}),"\n",(0,i.jsx)(n.p,{children:'The vhost component may be absent; this is indicated by the\nlack of a "/" character following the amqp_authority.  An\nabsent vhost component is not equivalent to an empty\n(i.e. zero-length) vhost name.'}),"\n",(0,i.jsx)(n.h2,{id:"handling-of-absent-components",children:"Handling of absent components"}),"\n",(0,i.jsx)(n.p,{children:"Certain URI components (the port, username, password,\nvhost and query) may be absent from a URI.  The host may not be\nabsent, but may be zero-length; for the purposes of this\nsection, a zero-length host is treated as absent."}),"\n",(0,i.jsx)(n.p,{children:"Apart from the port (which is covered in the section 2.2\nabove), this specification does not mandate how\nimplementations should handle absent components.  Possible\napproaches include, but are not limited to, the following:"}),"\n",(0,i.jsxs)("ul",{children:[(0,i.jsx)("li",{children:"An absent component may be substituted with a default\nvalue."}),(0,i.jsx)("li",{children:"A user-facing application may prompt the user to provide\nthe value for an absent component."}),(0,i.jsx)("li",{children:"An absent component may cause an error."})]}),"\n",(0,i.jsx)(n.p,{children:"Furthermore, an application may follow different strategies\nfor different c

1omponents."}),"\n",(0,i.jsx)(n.p,{children:'For example, the URI "amqp://", in which all components are\nabsent, might result in an client library using a set\nof defaults which correspond to a connection to a local RabbitMQ\nserver, authenticating as a guest user.  This would be\nconvenient for development purposes.'}),"\n",(0,i.jsx)(n.h2,{id:"the-amqps-uri-scheme",children:'The "amqps" URI scheme'}),"\n",(0,i.jsx)(n.p,{children:'The "amqps" URI scheme is used to instruct a client\nto make an secured connection to the server.'}),"\n",(0,i.jsx)(n.p,{children:"The AMQP 0-9-1 specification assume that the\nunderlying transport layer provides reliable\nbyte stream-oriented virtual circuits.  When it is not\nnecessary to secure the traffic on the network, TCP/IP\nconnections are typically used."}),"\n",(0,i.jsxs)(n.p,{children:["In cases where the traffic must be secured, TLS (see ",(0,i.jsx)("a",{href:"http://tools.ietf.org/rfc/rfc5246.txt",children:"RFC5246"}),')\ncan be used.  Current practice is simply to layer AMQP\n0-9-1 on top of TLS to form "AMQPS" (analogously to the\nway HTTPS layers HTTP on top of TLS).  AMQP 0-9-1 does\nnot provide a way for a non-secured connection to be\nupgraded to a secured connection. So a server that supports\nboth secured and non-secured connections must listen on\ndistinct ports for the two types of connections.']}),"\n",(0,i.jsx)(n.p,{children:'Apart from the scheme identifier, the syntax of the "amqps"\nURI scheme is identical to that of the "amqp" URI scheme:'}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{children:'amqps_URI      = "amqps://" amqp_authority [ "/" vhost ]\n'})}),"\n",(0,i.jsx)(n.p,{children:'The interpretation of an amqps URI differs from the\ncorresponding "plain" URI in two ways. In all other respects,\nthe interpretation is the same.'}),"\n",(0,i.jsxs)("ul",{children:[(0,i.jsx)("li",{children:'The client must act as a TLS client, and begin the\nTLS handshake as soon as the underlying TCP/IP connection\nhas been established. All AMQP 0-9-1 protocol data is sent as TLS\n"application data".  Other than this, normal AMQP 0-9-1 behaviour\nis followed.'}),(0,i.jsx)("li",{children:'If the port number is absent from the URI, the\nIANA-assigned port number for "amqps", 5671, should be\nused.'})]}),"\n",(0,i.jsx)(n.h2,{id:"security-considerations",children:"Security Considerations"}),"\n",(0,i.jsx)(n.p,{children:"As discussed in the section 2.3 above, URIs will often\nbe supplied to applications as configuration settings.  In\nsuch contexts, if the password cannot be incorporated into\nthe URI, then it will simply be supplied as a separate\nconfiguration setting. This reduces the benefit of the use\nof a URI without any increase in security. For this\nreason, this specification overrides RFC3986's deprecation\nof passwords within the userinfo component."}),"\n",(0,i.jsx)(n.p,{children:"Developers should feel free use the password component\nwhenever this does not impact security.  Nonetheless, they\nshould be aware that the contents of the password component\nmay be sensitive, and they should avoid leaking it (e.g. the\nfull URI should not appear in exception messages or log\nrecords, which might be visible to less privileged\npersonnel)."}),"\n",(0,i.jsx)(n.h2,{id:"appendix-a-examples",children:"Appendix A: Examples"}),"\n",(0,i.jsx)(n.p,{children:"Below is a table of examples that show how URIs should be\nparsed according to this specification.  Many of these\nexamples are intended to demonstrate edge cases in order to\nelucidate the specification and provide test cases for code\nthat parses URIs. Each row shows a URI, and the resulting\noctet sequences for each component.  Those octet sequences\nare enclosed in double quotes. Empty cells indicate absent\ncomponents, as described in section 3."}),"\n",(0,i.jsxs)("table",{children:[(0,i.jsx)("thead",{children:(0,i.jsxs)("tr",{children:[(0,i.jsx)("th",{children:"URI"}),(0,i.jsx)("th",{children:"Username"}),(0,i.jsx)("th",{children:"Password"}),(0,i.jsx)("th",{children:"Host"}),(0,i.jsx)("th",{children:"Port"}),(0,i.jsx)("th",{children:"Vhost"})]})}),(0,i.jsxs)("tbody",{children:[(0,i.jsxs)("tr",{children:[(0,i.jsxs)("td",{children:["amqp://user",":pass","@host:10000/vhost"]}),(0,i.jsx)("td",{children:'"user"'}),(0,i.jsx)("td",{children:'"pass"'}),(0,i.jsx)("td",{children:'"host"'}),(0,i.jsx)("td",{children:"10000"}),(0,i.jsx)("td",{children:'"vhost"'})]}),(0,i.jsxs)("tr",{children:[(0,i.jsxs)("td",{children:["amqp://user",":passw","%23rd@host:10000/vhost"]}),(0,i.jsx)("td",{children:'"user"'}),(0,i.jsx)("td",{children:'"passw#rd"'}),(0,i.jsx)("td",{children:'"host"'}),(0,i.jsx)("td",{children:"10000"}),(0,i.jsx)("td",{children:'"vhost"'})]}),(0,i.jsxs)("tr",{children:[(0,i.jsx)("td",{children:"amqp://user%61:%61pass@ho%61st:10000/v%2fhost"}),(0,i.jsx)("td",{children:'"usera"'}),(0,i.jsx)("td",{children:'"apass"'}),(0,i.jsx)("td",{children:'"hoast"'}),(0,i.jsx)("td",{children:"10000"}),(0,i.jsx)("td",{children:'"v/host"'})]}),(0,i.jsxs)("tr",{children:[(0,i.jsx)("td",{children:"amqp://"}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{})]}),(0,i.jsxs)("tr",{children:[(0,i.jsx)("td",{children:"amqp://:@/"}),(0,i.jsx)("td",{children:'""'}),(0,i.jsx)("td",{children:'""'}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{children:'""'})]}),(0,i.jsxs)("tr",{children:[(0,i.jsx)("td",{children:"amqp://user@"}),(0,i.jsx)("td",{children:'"user"'}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{})]}),(0,i.jsxs)("tr",{children:[(0,i.jsxs)("td",{children:["amqp://user",":pass","@"]}),(0,i.jsx)("td",{children:'"user"'}),(0,i.jsx)("td",{children:'"pass"'}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{})]}),(0,i.jsxs)("tr",{children:[(0,i.jsx)("td",{children:"amqp://host"}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{children:'"host"'}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{})]}),(0,i.jsxs)("tr",{children:[(0,i.jsx)("td",{children:"amqp://:10000"}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{children:"10000"}),(0,i.jsx)("td",{})]}),(0,i.jsxs)("tr",{children:[(0,i.jsx)("td",{children:"amqp:///vhost"}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{children:'"vhost"'})]}),(0,i.jsxs)("tr",{children:[(0,i.jsx)("td",{children:"amqp://host/"}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{children:'"host"'}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{children:'""'})]}),(0,i.jsxs)("tr",{children:[(0,i.jsx)("td",{children:"amqp://host/%2f"}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{children:'"host"'}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{children:'"/"'})]}),(0,i.jsxs)("tr",{children:[(0,i.jsx)("td",{children:"amqp://[::1]"}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{children:'"[::1]" (i.e. the IPv6 address ::1)'}),(0,i.jsx)("td",{}),(0,i.jsx)("td",{})]})]})]}),"\n",(0,i.jsx)(n.h2,{id:"appendix-b-query-parameters",children:"Appendix B: Query parameters"}),"\n",(0,i.jsx)(n.p,{children:"Clients may require further parameterisation to define how\nthey should connect to servers. The standard URI query syntax\nmay be used to provide additional information to the client."}),"\n",(0,i.jsxs)(n.p,{children:["Query parameters may be more implementation-specific than other\nURI parts; as such this document will not attempt to prescribe\nhow they should be used. However, we have documented how the\n",(0,i.jsx)("a",{href:"./uri-query-parameters",children:"officially supported clients read U

1RI query parameters"}),"."]})]})}function l(e={}){let{wrapper:n}={...(0,o.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(c,{...e})}):c(e)}},28453(e,n,t){t.d(n,{R:()=>r,x:()=>a});var s=t(96540);let i={},o=s.createContext(i);function r(e){let n=s.useContext(o);return s.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function a(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:r(e.components),s.createElement(o.Provider,{value:n},e.children)}}}]);