URI Query Parameters

Overview

This page is a less-formal companion to the URI specification and TLS guides, documenting how the officially-supported clients interpret URI parameters. Currently only the Erlang client does so.

The Federation and Shovel plugins specify connections to other brokers using URIs, and are implemented using the Erlang client, so they take all the parameters described here for it.

The Basics

Query parameters are added to the URI in the usual way. Any parameter can be omitted. The client will pick sensible defaults when they are.

Example A

An example connection URI with TLS disabled:

amqp://myhost?heartbeat=5&connection_timeout=10000

This specifies a (non-encrypted) network connection to the host myhost. The heartbeat interval is set to 5 seconds, and connection timeout is set to 10 seconds (10,000 milliseconds). Other parameters are set to their default values.

Example B

In the following example URI, TLS and TLS peer verification) on the client side of the connection are enabled:

amqps://myhost?cacertfile=/path/to/ca_certificate.pem
  &certfile=/path/to/client_certificate.pem
  &keyfile=/path/to/client_key.pem
  &verify=verify_peer
  &server_name_indication=myhost

Example C

In the following example URI, TLS is enabled but TLS peer verification) on the client side of the connection is disabled:

amqps://myhost?cacertfile=/path/to/ca_certificate.pem
  &certfile=/path/to/client_certificate.pem
  &keyfile=/path/to/client_key.pem
  &verify=verify_none
  &server_name_indication=myhost

TLS Parameters

This specifies an encrypted network connection to the host myhost. Absolute paths to the certificate files are provided. verify_peer ensures that certificate chain of trust is verified, and server_name_indication validates the CN value in the server's certificate against the hostname myhost.

Parameter name	Description
cacertfile certfile keyfile	Paths to files to use in order to present a client-side SSL certificate to the server. Only of use for the amqps scheme.
verify server_name_indication	Only of use for the amqps scheme and used to configure verification of the server's x509 (TLS) certificate. Note: It is highly recommended to use both values. See the TLS guide to learn more about TLS support in RabbitMQ in general and specifically the Erlang client section.
auth_mechanism	SASL authentication mechanisms to consider when negotiating a mechanism with the server. This parameter can be specified multiple times, e.g. ?auth_mechanism=plain&auth_mechanism=amqplain, to specify multiple mechanisms.
heartbeat	Heartbeat timeout value in seconds (an integer) to negotiate with the server.
connection_timeout	Time in milliseconds (an integer) to wait while establishing a TCP connection to the server before giving up.
channel_max	Maximum number of channels to permit on this connection.

TLS options can also be specified globally using the amqp_client.ssl_options configuration key in advanced.config like so:

{amqp_client, [
    {ssl_options, [
        {cacertfile, "path-to-ca-certificate"},
        {certfile, "path-to-certificate"},
        {keyfile, "path-to-keyfile"},
        {verify, verify_peer}
    ]}
]}.

They will be merged with the TLS parameters from the URI (the latter will take precedence) and affect all outgoing RabbitMQ Erlang client connections on the node, including plugins that use the client internally (Federation, Shovel, etc). Please see the TLS guide for details.