Pivotal RabbitMQ v3.x

AMQP URI Specification

This specification defines an “amqp” URI scheme. Conforming URIs represent the information needed to connect to an AMQP server (for versions 0-8 and 0-9-1 of AMQP).

1. Introduction

AMQP is a protocol standard for messaging middleware. A number of different versions of AMQP have been published, which differ significantly in their goals. The scope of this specification is limited to versions 0-8 and 0-9-1 of AMQP (0-9-1 being a refinement of 0-8). An AMQP client connects to an AMQP server in order to publish and consume messages according to the messaging model.

Several pieces of information are needed by a client to establish an AMQP 0-8/0-9-1 connection and put it into a state ready for normal use (i.e. when the server has replied to the client with the connection.start-ok AMQP method). These connection parameters include:

  • The parameters needed to establish the underlying TCP/IP connection to the server (i.e. host address and port).
  • Information to authenticate the client. AMQP uses SASL for authentication. Typically the PLAIN mechanism is used, and so the authentication parameters consist of a username and password.
  • The name of the “virtual host” (or vhost) that specifies the namespace for entities (exchanges and queues) referred to by the protocol. Note that this is not virtual hosting in the HTTP sense.

An AMQP client application will typically obtain all these parameters from the same source (e.g. a configuration file). They must then be relayed to the AMQP client library (the library that implements the AMQP) in order for it to set up the connection. So it is convenient if the connection parameters can be combined into a single character string, rather than as distinct configuration settings. That means that only one configuration setting is needed, and only one value has to be passed to the AMQP client library.

But combining the connection parameters into a single string requires a convention, understood by the AMQP client library, about exactly how the connection parameters are represented and delimited. It is desirable to standardise that convention, so that it may be implemented consistently by many AMQP client libraries. An obvious basis for such a standard is the generic syntax for URIs defined in RFC3986.

The purpose of this specification is to define the “amqp” and “amqps” URI schemes which represent the AMQP 0-8/0-9-1 connection parameters within the generic URI syntax.

2. The “amqp” URI scheme

The syntax of an AMQP URI is defined by the following ABNF rules. All names in these rules not defined here are taken from RFC3986.

amqp_URI       = "amqp://" amqp_authority [ "/" vhost ] [ "?" query ]

amqp_authority = [ amqp_userinfo "@" ] host [ ":" port ]

amqp_userinfo  = username [ ":" password ]

username       = *( unreserved / pct-encoded / sub-delims )

password       = *( unreserved / pct-encoded / sub-delims )

vhost          = segment

Once a URI has been successfully parsed according to this syntax, the AMQP connection parameters are determined as described in the following sections.

2.1. Host

The host to which the underlying TCP connection is made is determined from the host component according to RFC3986, section 3.2.2. Note that according to the ABNF, the host component may not be absent, but it may be zero-length.

2.2. Port

The port number to which the underlying TCP connection is made is determined from the port component according to RFC3986. The port component may be absent, indicated by the lack of the “:” character separating it from the host. If it is absent, then the IANA-assigned port number for AMQP, 5672, should be substituted instead.

2.3. Username and password

If present, the username and password components should be used in the SASL exchange that occurs via the and AMQP methods. Any percent-encoded octets in the username and password should be decoded before they are used in the SASL exchange, and the resulting octet sequences should be regarded as UTF-8 encoded.

Both the username and password may be absent; their absence is indicated by the lack of the “@” character separating the amqp_userinfo from the host. If the username is present, the password may be absent; this is indicated by the lack of the “:” character separating it from the username. Zero-length usernames and passwords are not equivalent to absent usernames and passwords.

RFC3986 states that “A password appearing within the userinfo component is deprecated and should be considered an error” (section 7.5). While this is sound advice in the context of user-facing applications (e.g. web browsers) and for URIs that might be stored and displayed insecurely, it is not necessarily valid for AMQP applications. Many AMQP applications are server-based, and make AMQP connections on behalf of the application as a whole rather than for specific users. So the username and password identify the application rather than a human user, and are likely to be included with connection parameters appearing in a secure store of configuration settings. User-facing AMQP applications, which make AMQP connections on behalf of specific users, are also possible. In such cases the username and password may be provided by the user to identify themselves. But such AMQP applications are the exception rather than the rule. Thus authors of AMQP applications implementing this specification should not consider themselves bound by section 7.5 of RFC3986. Please also see section 5 (“Security Considerations”) below.

2.4. Vhost

The vhost component is used as the basis for the virtual-host field of the AMQP method. Any percent-encoded octets in the vhost should be decoded before the it is passed to the server.

Note that:

  • The vhost component of the URI does not include the leading “/” character from the path. This makes it possible to refer to any vhost, not only those that begin with a “/” character.
  • The vhost is a single segment. Therefore, any “/” characters that appear in the vhost name must be percent-encoded. URIs with multi-segment paths do not obey this specification. (They are reserved to allow future revisions of this URI scheme to refer to AMQP entities other than vhosts.)

The vhost component may be absent; this is indicated by the lack of a “/” character following the amqp_authority. An absent vhost component is not equivalent to an empty (i.e. zero-length) vhost name.

3. Handling of absent components

Certain URI components (the port, username, password, vhost and query) may be absent from a URI. The host may not be absent, but may be zero-length; for the purposes of this section, a zero-length host is treated as absent.

Apart from the port (which is covered in the section 2.2 above), this specification does not mandate how implementations should handle absent components. Possible approaches include, but are not limited to, the following:

  • An absent component may be substituted with a default value.
  • A user-facing application may prompt the user to provide the value for an absent component.
  • An absent component may cause an error.

Furthermore, an application may follow different strategies for different components.

For example, the URI “amqp://”, in which all components are absent, might result in an AMQP client library using a set of defaults which correspond to a connection to a local AMQP server, authenticating as a guest user. This would be convenient for development purposes and casual use of AMQP applications.

4. The “amqps” URI scheme

The “amqps” URI scheme is used to instruct an AMQP client to make an secured connection to the AMQP server.

The AMQP 0-8 and 0-9-1 specifications assume that the underlying transport layer provides reliable byte-stream-oriented virtual circuits. When it is not necessary to secure the traffic on the network, TCP/IP connections are typically used.

In cases where the traffic must be secured, TLS (see RFC5246) can be used. Current practice is simply to layer AMQP 0-8/0-9-1 on top of TLS to form “AMQPS” (analogously to the way HTTPS layers HTTP on top of TLS). AMQP 0-8/0-9-1 does not provide a way for a non-secured connection to be upgraded to a secured connection. So a server that supports both secured and non-secured connections must listen on distinct ports for the two types of connections.

Apart from the scheme identifier, the syntax of the “amqps” URI scheme is identical to that of the “amqp” URI scheme:

amqps_URI      = "amqps://" amqp_authority [ "/" vhost ]

The interpretation of an AMQPS URI differs from the corresponding AMQP URI in two ways. In all other respects, the interpretation is the same.

  • The AMQP client must act as a TLS client, and begin the TLS handshake as soon as the underlying TCP/IP connection has been established. All AMQP data is sent as TLS “application data”. Other than this, normal AMQP behaviour is followed.
  • If the port number is absent from the URI, the IANA-assigned port number for “amqps”, 5671, should be used.

5. Security Considerations

As discussed in the section 2.3 above, AMQP URIs will often be supplied to applications as configuration settings. In such contexts, if the password cannot be incorporated into the URI, then it will simply be supplied as a separate configuration setting. This reduces the benefit of the use of an AMQP URI without any increase in security. For this reason, this specification overrides RFC3986’s deprecation of passwords within the userinfo component.

Implementers of AMQP applications should feel free use the password component whenever this does not impact security. Nonetheless, they should be aware that the contents of the password component may be sensitive, and they should avoid leaking it (e.g. the full AMQP URI should not appear in exception messages or log records, which might be visible to less privileged personnel).

Appendix A - Examples

Below is a table of examples that show how URIs should be parsed according to this specification. Many of these examples are intended to demonstrate edge cases in order to elucidate the specification and provide test cases for code that parses AMQP URIs. Each row shows a URI, and the resulting octet sequences for each component. Those octet sequences are enclosed in double quotes. Empty cells indicate absent components, as described in section 3.

URI Username Password Host Port Vhost
amqp://user:pass@host:10000/vhost “user” “pass” “host” 10000 “vhost”
amqp://user%61:%61pass@ho%61st:10000/v%2fhost “usera” “apass” “hoast” 10000 “v/host”
amqp://:@/ “” “” “”
amqp://user@ “user”
amqp://user:pass@ “user” “pass”
amqp://host “host”
amqp://:10000 10000
amqp:///vhost “vhost”
amqp://host/ “host” “”
amqp://host/%2f “host” “/”
amqp://[::1] “[::1]” (i.e. the IPv6 address ::1)

Appendix B - Query parameters

AMQP clients may require further parameterisation to define how they should connect to servers. The standard URI query syntax may be used to provide additional information to the client.

Query parameters may be more implementation-specific than other URI parts; as such this document will not attempt to prescribe how they should be used. However, we have documented how the officially supported clients read URI query parameters here.

Appendix C - Other proposals for an “amqp” URI scheme

This specification is not the first proposal for an “amqp” URI scheme. In particular, the Apache QPID project has made two distinct proposals (<>, <>).

Compared with those proposals, this specification has the following characteristics:

  • It is precise.
  • It has a clear basis in the relevant RFCs: RFC3986 and RFC2718.
  • It focuses on AMQP 0-8/0-9-1, rather than considering other versions of the AMQP standard.
  • It leaves out of scope features that do not fit well into the generic URI syntax established by RFC3986, and that might be better achieved in other ways (e.g. listing multiple server addresses).
  • It restricts the vhost to a single segment, reserving URIs with multiple-segment paths for future use.