STOMP Plugin | RabbitMQ
Skip to main content Version: 4.4 Overview RabbitMQ supports STOMP via a plugin that ships in the core distribution. The plugin supports STOMP versions 1.0 through 1.2 with some extensions and restrictions . STOMP clients can interoperate with other protocols. All the functionality in the management UI and several other plugins can be used with STOMP, although there may be some limitations or the need to tweak the defaults.
Enabling the Plugin The STOMP plugin is included in the RabbitMQ distribution. Before clients can successfully connect, it must be enabled using rabbitmq-plugins : rabbitmq-plugins enable rabbitmq_stomp Plugin Configuration Connection Limit Starting with RabbitMQ 4.4, set stomp.max_connections to limit concurrent STOMP connections per node. The default is infinity (no limit). TCP Listeners When no configuration is specified the STOMP Adapter will listen on all interfaces on port 61613 and have a default user login/passcode of guest / guest .
To change the listener port, edit your Configuration file , to contain a tcp_listeners variable for the rabbitmq_stomp application. For example, a minimalistic configuration file which changes the listener port to 12345 would look like: stomp.listeners.tcp.1 = 12345 while one which changes the listener to listen only on localhost (for both IPv4 and IPv6) would look like: stomp.listeners.tcp.1 = 127.0.0.1:61613 stomp.listeners.tcp.2 = ::1:61613 TCP Listener Options The plugin supports TCP listener option configuration.
The settings use a common prefix, stomp.tcp_listen_options , and control things such as TCP buffer sizes, inbound TCP connection queue length, whether TCP keepalives are enabled and so on. See the Networking guide for details. stomp.listeners.tcp.1 = 127.0.0.1:61613 stomp.listeners.tcp.2 = ::1:61613 stomp.tcp_listen_options.backlog = 4096 stomp.tcp_listen_options.recbuf = 131072 stomp.tcp_listen_options.sndbuf = 131072 stomp.tcp_listen_options.keepalive = true stomp.tcp_listen_options.nodelay = true stomp.tcp_listen_options.exit_on_close = true stomp.tcp_listen_options.send_timeout = 120 TLS Support To use TLS for STOMP connections, TLS must be configured in the broker.
To enable TLS-enabled STOMP connections, add a TLS listener for STOMP using the stomp.listeners.ssl.* configuration keys. The plugin will use core RabbitMQ server certificates and key (just like AMQP 0-9-1 and AMQP 1.0 listeners do): ssl_options.cacertfile = /path/to/tls/ca_certificate.pem ssl_options.certfile = /path/to/tls/server_certificate.pem ssl_options.keyfile = /path/to/tls/server_key.pem ssl_options.verify = verify_peer ssl_options.fail_if_no_peer_cert = true stomp.listeners.tcp.1 = 61613 # default TLS-enabled port for STOMP connections stomp.listeners.ssl.1 = 61614 This configuration creates a standard TCP listener on port 61613 and a TLS listener on port 61614.
When a TLS listener is set up, you may want to deactivate all non-TLS ones. This can be configured like so: stomp.listeners.tcp = none stomp.listeners.ssl.1 = 61614 Default User The RabbitMQ STOMP adapter allows CONNECT frames to omit the login and passcode headers if a default is configured. To configure a default login and passcode, add a default_user section to the rabbitmq_stomp application configuration. For example: stomp.default_user = guest stomp.default_pass = guest The configuration example above makes guest / guest the default login/passcode pair.
Authentication with TLS/x509 client certificates The plugin can authenticate TLS-enabled connections by extracting a name from the client's TLS (x509) certificate, without using a password. For safety the server must be configured with the TLS options fail_if_no_peer_cert set to true and verify set to verify_peer , to force all TLS clients to have a verifiable client certificate. To switch this feature on, set ssl_cert_login to true for the rabbitmq_stomp application.
For example: stomp.ssl_cert_login = true By default this will set the username to an RFC4514-ish string form of the certificate's subject's Distinguished Name, similar to that produced by OpenSSL's "-nameopt RFC2253" option. To use the Common Name instead, add: ssl_cert_login_from = common_name to your configuration. Note that: The authenticated user must exist in the configured authentication / authorisation backend(s).
Clients must not supply login and passcode headers. Implicit Connect If you configure a default user or use SSL client certificate authentication, you can also choose to allow clients to omit the CONNECT frame entirely. In this mode, if the first frame sent on a session is not a CONNECT , the client is automatically connected as the default user or the user supplied in the SSL certificate. To enable implicit connect, set implicit_connect to true for the rabbit_stomp application.
For example: stomp.default_user = guest stomp.default_pass = guest stomp.implicit_connect = true Implicit connect is not enabled by default. Note: A client causing an implicit connect will not receive a CONNECTED frame from the server. Proxy Protocol The STOMP plugin supports the proxy protocol . This feature is turned off by default. To turn it on for STOMP clients: stomp.proxy_protocol = true See the Networking Guide for more information about the proxy protocol.
Frame Size Limit By default frame size limit is 4Mb. When a frame exceeds the limit it's an error and connection closed. stomp.max_frame_size = 4 * 1024 * 1024 Destinations The STOMP specification does not prescribe what kinds of destinations a broker must support, instead the value of the destination header in SEND and MESSAGE frames is broker-specific. The RabbitMQ STOMP adapter supports a number of different destination types: /exchange -- SEND to arbitrary routing keys and SUBSCRIBE to arbitrary binding patterns; /queue -- SEND and SUBSCRIBE to queues managed by the STOMP gateway; /amq/queue -- SEND and SUBSCRIBE to queues created outside the STOMP gateway; /topic -- SEND and SUBSCRIBE to transient and durable topics; /temp-queue/ -- create temporary queues (in reply-to headers only).
AMQP 0-9-1 Semantics The destination header on a MESSAGE frame is set as though the message originated from a SEND frame: messages published to the default exchange are given the destination /queue/ queuename ; messages published to amq.topic are given the destination /topic/ routing_key ; all other messages are given the destination /exchange/ exchange_name [ / routing_key ]. If / , % or non-ascii bytes are in the queuename , exchange_name or routing_key , they are each replaced with the sequence % dd , where dd is the hexadecimal code for the byte.
Because of these rules the destination on a MESSAGE frame may not exactly match that on a SEND that published it. Different destinations have different queue parameter defaults. They can be controlled explicitly via headers, as explained further in this guide. Exchange Destinations Any exchange/queue or exchange/routing-key combination can be accessed using destinations prefixed with /exchange . For SUBSCRIBE frames, a destination of the form /exchange/<name>[/<pattern>] can be used.
This destination: creates an exclusive, auto-delete queue on <name> exchange; if <pattern> is supplied, binds the queue to <name> exchange using <pattern> ; and registers a subscription against the queue, for the current STOMP session. For SEND frames, a destination of the form /exchange/<name>[/<routing-key>] can be used. This destination: sends to exchange <name> with the routing key <routing-key> . Note: Exchange destinations are not suitable for consuming messages from an existing queue.
A new queue is created for each subscriber and is bound to the specified exchange using the supplied routing key. To work with existing queues, use /amq/queue destinations. Queue Destinations For simple queues, destinations of the form /queue/<name> can be used. Queue destinations deliver each message to at most on
The rest of this page is on the live site.