Menu

HTTP Server Configuration for Plugins with HTTP API

Overview

There are several plugins that expose an HTTP or HTTP-based (WebSockets) API to clients.

This guide covers various HTTP-specific settings that are applicable to multiple plugins, e.g. rabbitmq-management, rabbitmq-web-stomp, rabbitmq-web-mqtt, rabbitmq-top, and others. In this guide these plugins will be referenced as "HTTP API plugins" or "plugins based on the Web dispatch mechanism".

The rabbitmq-web-dispatch plugin provides a foundation for such plugins. It is not a plugin that has to be enabled directly. When a plugin that provides an HTTP API is enabled, it will enable rabbitmq-web-dispatch as a dependency.

Configuration

Plugins that are based on the Web dispatch mechanism take a listener configuration item to configure their listening HTTP port. In this page we will give examples for the rabbitmq_management application, but the same configuration can be applied to rabbitmq_web_stomp, rabbitmq_web_mqtt, and other HTTP API plugins.

The listener configuration item can contain the following keys:

  • port (mandatory)
  • ip (to listen on only one interface)
  • ssl (to enable TLS/HTTPS)
  • ssl_opts (to configure TLS options for HTTPS)
  • cowboy_opts (to configure the embedded HTTP server, Cowboy.

Listening on a Single Interface

Use the listener.ip key to specify an interface for Cowboy to bind to. For example:

management.listener.port = 15672
management.listener.ip   = 127.0.0.1

Or, using the classic config format:

[{rabbitmq_management,
  [{listener, [{port, 15672},
               {ip, "127.0.0.1"}
              ]}
  ]}
].

Enabling TLS (HTTPS)

Set listener.ssl to true to turn on TLS for a listener. Use listener.ssl_opts to specify TLS options. These are named the same as TLS options for other protocols, see the RabbitMQ TLS guide for more information.

For convenience, if listener.ssl_opts are not specified then will use the same options as the main RabbitMQ server does for AMQP 0-9-1 and AMQP 1.0 over TLS except that client certificate verification will turned off by default. To use client certificate verification, specify listener.ssl_opts explicitly.

For example:

management.listener.port = 15672
management.listener.ssl  = true

management.listener.ssl_opts.cacertfile = /path/to/cacert.pem
management.listener.ssl_opts.certfile   = /path/to/cert.pem
management.listener.ssl_opts.keyfile    = /path/to/key.pem

The same example using the classic config format:

[{rabbitmq_management,
  [{listener, [{port,     15672},
               {ssl,      true},
               {ssl_opts, [{cacertfile, "/path/to/cacert.pem"},
                           {certfile,   "/path/to/cert.pem"},
                           {keyfile,    "/path/to/key.pem"}]}
              ]}
  ]}
].

Advanced HTTP Server Options

Cowboy provides a number of options that can be used to customize the behavior of the server. They are configured using the cowboy_opts listener options.

Response Compression

Response compression is enabled by default when no listener.cowboy_opts are configured.

To enable response compression explicitly, set the listener.cowboy_opts.compress option to true:

[{rabbitmq_management,
  [{listener, [{port,        15672},
               {cowboy_opts, [{compress, true}]}
              ]}
  ]}
].

Client Inactivity Timeouts

Some HTTP API endpoints respond quickly, others may need to return or stream a sizeable data set to the client (e.g. many thousands of connections) or perform an operation that takes time proportionally to the input (e.g. import a large definitions file). In those cases the amount of time it takes to process the request can exceed certain timeouts in the Web server as well as HTTP client.

It is possible to bump Cowboy timeouts using the listener.cowboy_opts.idle_timeout, listener.cowboy_opts.inactivity_timeout, and listener.cowboy_opts.request_timeout options:

[{rabbitmq_management,
  [{listener, [{port,        15672},
               {cowboy_opts, [{compress, true},
                              %% 120 seconds
                              {idle_timeout,      120000},
                              {inactivity_timeout,120000},
                              {request_timeout,   120000}]}
              ]}
  ]}
].

All values are in milliseconds and default to 60000 (1 minute). It is recommended that all timeouts are increased at the same time.

Getting Help and Providing Feedback

If you have questions about the contents of this guide or any other topic related to RabbitMQ, don't hesitate to ask them on the RabbitMQ mailing list.

Help Us Improve the Docs <3

If you'd like to contribute an improvement to the site, its source is available on GitHub. Simply fork the repository and submit a pull request. Thank you!