Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 3. Configuring messaging protocols in network connections

You can configure messaging protocols, such as AMQP or MQTT, to customize how acceptors handle incoming connections over the network.

The broker supports the following protocols:

  • AMQP
  • MQTT
  • OpenWire
  • STOMP
Note

In addition to the protocols above, the broker also supports its own native protocol known as "Core". Past versions of this protocol were known as "HornetQ" and used by Red Hat JBoss Enterprise Application Platform.

3.1. Default acceptors
Copy link

The default AMQ Broker configuration includes acceptors for Core, AMQP, MQTT, and STOMP protocols, plus an acceptor that supports all protocols. You can customize the acceptors for your environment.

The default acceptors are configured in the <broker_instance_dir>/etc/broker.xml file. 

<configuration>
  <core>
    ...
    <acceptors>

      <!-- All-protocols acceptor -->
      <acceptor name="artemis">tcp://0.0.0.0:61616?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=CORE,AMQP,STOMP,HORNETQ,MQTT,OPENWIRE;useEpoll=true;amqpCredits=1000;amqpLowCredits=300</acceptor>

      <!-- AMQP Acceptor. Listens on default AMQP port for AMQP traffic -->
      <acceptor name="amqp">tcp://0.0.0.0:5672?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=AMQP;useEpoll=true;amqpCredits=1000;amqpLowCredits=300</acceptor>

      <!-- STOMP Acceptor -->
      <acceptor name="stomp">tcp://0.0.0.0:61613?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=STOMP;useEpoll=true</acceptor>

      <!-- HornetQ Compatibility Acceptor. Enables HornetQ Core and STOMP for legacy HornetQ clients. -->
      <acceptor name="hornetq">tcp://0.0.0.0:5445?anycastPrefix=jms.queue.;multicastPrefix=jms.topic.;protocols=HORNETQ,STOMP;useEpoll=true</acceptor>

      <!-- MQTT Acceptor -->
      <acceptor name="mqtt">tcp://0.0.0.0:1883?tcpSendBufferSize=1048576;tcpReceiveBufferSize=1048576;protocols=MQTT;useEpoll=true</acceptor>

    </acceptors>
    ...
  </core>
</configuration>
Copy to Clipboard Toggle word wrap

3.2. Parameters configured in default acceptors
Copy link

Review all the other parameters configured in the default acceptors and customize as required for your environment.

Expand
Table 3.1. Parameters configured in default acceptors
Acceptor(s)ParameterDescription

All-protocols acceptor

AMQP

STOMP

tcpSendBufferSize

Size of the TCP send buffer in bytes. The default value is 32768.

tcpReceiveBufferSize

Size of the TCP receive buffer in bytes. The default value is 32768.

TCP buffer sizes should be tuned according to the bandwidth and latency of your network.

In summary TCP send/receive buffer sizes should be calculated as:

buffer_size = bandwidth * RTT.

Where bandwidth is in bytes per second and network round trip time (RTT) is in seconds. RTT can be easily measured using the ping utility.

For fast networks you might want to increase the buffer sizes from the defaults.

All-protocols acceptor

AMQP

STOMP

HornetQ

MQTT

useEpoll

Use Netty epoll if using a system (Linux) that supports it. The Netty native transport offers better performance than the NIO transport. The default value of this option is true. If you set the option to false, NIO is used.

All-protocols acceptor

AMQP

amqpCredits

Maximum number of messages that an AMQP producer can send, regardless of the total message size. The default value is 1000.

To learn more about how credits are used to block AMQP messages, see Section 7.3.2, “Blocking AMQP producers”.

All-protocols acceptor

AMQP

amqpLowCredits

Lower threshold at which the broker replenishes producer credits. The default value is 300. When the producer reaches this threshold, the broker sends the producer sufficient credits to restore the amqpCredits value.

To learn more about how credits are used to block AMQP messages, see Section 7.3.2, “Blocking AMQP producers”.

HornetQ compatibility acceptor

anycastPrefix

Prefix that clients use to specify the anycast routing type when connecting to an address that uses both anycast and multicast. The default value is jms.queue.

For more information about configuring a prefix to enable clients to specify a routing type when connecting to an address, see Section 4.6, “Adding a routing type to an acceptor configuration”.

multicastPrefix

Prefix that clients use to specify the multicast routing type when connecting to an address that uses both anycast and multicast. The default value is jms.topic.

For more information about configuring a prefix to enable clients to specify a routing type when connecting to an address, see Section 4.6, “Adding a routing type to an acceptor configuration”.

Additional resources

You can configure a network connection to use specific messaging protocols.

Prerequisite

You created and configured a network connection. For more information, see Chapter 2, Configuring acceptors and connectors in network connections.

Procedure

  1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

  2. Add the protocols parameter to the URI for an acceptor and specify the protocol name: 

    <acceptor name="ampq">tcp://0.0.0.0:3232?protocols=AMQP</acceptor>
    Copy to Clipboard Toggle word wrap

    In this example, the acceptor is configured to receive messages on port 3232 by using the AMQP protocol. If you want to use multiple protocols, specify a comma-separated list of protocol names. For example: 

    <acceptor name="ampq">tcp://0.0.0.0:3232?protocols=AMQP,STOMP,MQTT</acceptor>
    Copy to Clipboard Toggle word wrap
    Note

    If the protocols parameter is omitted from the URI, all protocols are enabled.

3.4. Using AMQP with a network connection
Copy link

You can use the Advanced Message Queuing Protocol (AMQP) with a network connection to help enable interoperability with other messaging systems.

The broker supports the AMQP 1.0 specification. An AMQP link is a uni-directional protocol for messages between a source and a target, that is, a client and the broker.

An AMQP link has two endpoints, a sender and a receiver. When senders transmit a message, the broker converts it into an internal format, so it can be forwarded to its destination on the broker. Receivers connect to the destination at the broker and convert the messages back into AMQP before they are delivered.

If an AMQP link is dynamic, a temporary queue is created and either the remote source or the remote target address is set to the name of the temporary queue. If the link is not dynamic, the address of the remote target or source is used for the queue. If the remote target or source does not exist, an exception is sent.

A link target can also be a Coordinator, which is used to handle the underlying session as a transaction, either rolling it back or committing it.

Note

AMQP allows the use of multiple transactions per session, amqp:multi-txns-per-ssn, however the current version of AMQ Broker will support only single transactions per session.

Note

The details of distributed transactions (XA) within AMQP are not provided in the 1.0 version of the specification. If your environment requires support for distributed transactions, it is recommended that you use the AMQ Core Protocol JMS.

See the AMQP 1.0 specification for more information about the protocol and its features.

3.4.2. AMQP security
Copy link

The broker supports AMQP SASL Authentication. See Security for more information about how to configure SASL-based authentication on the broker.

3.5. Using MQTT with a network connection
Copy link

The broker supports MQTT v3.1.1 and v5.0 (and also the older v3.1 code message format). MQTT is a lightweight, client to server, publish/subscribe messaging protocol. MQTT reduces network traffic and a client’s code footprint. For these reasons, MQTT is ideally suited to constrained devices such as sensors and actuators and is quickly becoming the standard communication protocol for Internet of Things(IoT).

Procedure

  1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

  2. Add an acceptor with the MQTT protocol enabled. For example: 

    <acceptors>
  <acceptor name="mqtt">tcp://localhost:1883?protocols=MQTT</acceptor>
  ...
</acceptors>
    Copy to Clipboard Toggle word wrap

    MQTT includes several useful features:

    Quality of Service
    Each message can define a quality of service that is associated with it. The broker will attempt to deliver messages to subscribers at the highest quality of service level defined.
    Retained Messages

    Messages can be retained for a particular address. New subscribers to that address receive the last-sent retained message before any other messages, even if the retained message was sent before the client connected.

    Retained messages are stored in a queue named sys.mqtt.<topic name> and remain in the queue until a client deletes the retained message or, if an expiry is configured, until the message expires. When a queue is empty, the queue is not removed until you explicitly delete it. For example, the following configuration deletes a queue: 

    <address-setting match="$sys.mqtt.retain.#">
   <auto-delete-queues>true</auto-delete-queues>
   <auto-delete-addresses>true</auto-delete-addresses>
</address-setting>
    Copy to Clipboard Toggle word wrap
    Wildcard subscriptions
    MQTT addresses are hierarchical, similar to the hierarchy of a file system. Clients are able to subscribe to specific topics or to whole branches of a hierarchy.
    Will Messages
    Clients are able to set a "will message" as part of their connect packet. If the client abnormally disconnects, the broker will publish the will message to the specified address. Other subscribers receive the will message and can react accordingly.

3.5.1. MQTT properties
Copy link

You can append key-value pairs to the MQTT acceptor to configure connection properties. For example: 

<acceptors>
  <acceptor name="mqtt">tcp://localhost:1883?protocols=MQTT;receiveMaximum=50000;topicAliasMaximum=50000;maximumPacketSize;134217728;
serverKeepAlive=30;closeMqttConnectionOnPublishAuthorizationFailure=false</acceptor>
  ...
</acceptors>
Copy to Clipboard Toggle word wrap
receiveMaximum
Enables flow-control by specifying the maximum number of QoS 1 and 2 messages that the broker can receive from a client before an acknowledgment is required. The default value is 65535. A value of -1 disables flow-control from clients to the broker. This has the same effect as setting the value to 0 but reduces the size of the CONNACK packet.
topicAliasMaximum
Specifies for clients the maximum number of aliases that the broker supports. The default value is 65535. A value of -1 prevents the broker from informing the client of a topic alias limit. This has the same effect as setting the value to 0, but reduces the size of the CONNACK packet.
maximumPacketSize
Specifies the maximum packet size that the broker can accept from clients. The default value is 268435455. A value of -1 prevents the broker from informing the client of a maximum packet size, which means that no limit is enforced on the size of incoming packets.
serverKeepAlive
Specifies the duration the broker keeps an inactive client connection open. The configured value is applied to the connection only if it is less than the keep-alive value configured for the client or if the value configured for the client is 0. The default value is 60 seconds. A value of -1 means that the broker always accepts the client’s keep alive value (even if that value is 0).
closeMqttConnectionOnPublishAuthorizationFailure
By default, if a PUBLISH packet fails due to a lack of authorization, the broker closes the network connection. If you want the broker to sent a positive acknowledgment instead of closing the network connection, set closeMqttConnectionOnPublishAuthorizationFailure to false.

3.6. Using Openwire with a network connection
Copy link

You can use use the OpenWire protocol to allow JMS clients to communicate with the AMQ Broker over a network connection. Use this protocol to communicate with older versions of AMQ Broker.

Currently AMQ Broker supports OpenWire clients that use standard JMS APIs only.

For examples of how to configure an Openwire network connection, see the Openwire example.

3.7. Using Stomp with a network connection
Copy link

To allow STOMP clients to exchange messages with AMQ Broker, configure a network connection that uses the lightweight, text-oriented STOMP protocol.

The broker supports STOMP 1.0, 1.1 and 1.2. STOMP clients are available for several languages and platforms making it a good choice for interoperability.

For an example of how to configure a broker with STOMP, see the STOMP example.

The following limitations apply when a network connection uses the STOMP protocol:

  1. The broker currently does not support virtual hosting, which means the host header in CONNECT frames are ignored.
  2. Message acknowledgments are not transactional. The ACK frame cannot be part of a transaction, and it is ignored if its transaction header is set.

3.7.1. Configuring IDs for STOMP Messages
Copy link

STOMP messages received through a JMS consumer or a QueueBrowser do not contain any JMS properties, such as JMSMessageID. You can configure a broker parameter that sets a message ID on each incoming STOMP message.

Procedure

  1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

  2. Set the stompEnableMessageId parameter to true for the acceptor used for STOMP connections, as shown in the following example: 

    <acceptors>
  <acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;stompEnableMessageId=true</acceptor>
  ...
</acceptors>
    Copy to Clipboard Toggle word wrap

    By using the stompEnableMessageId parameter, each stomp message sent using this acceptor has an extra property added. The property key is amq-message-id and the value is a String representation of an internal message id prefixed with “STOMP”, as shown in the following example: 

    amq-message-id : STOMP12345
    Copy to Clipboard Toggle word wrap

    If stompEnableMessageId is not specified in the configuration, the default value is false.

3.7.2. Setting a connection time to live
Copy link

If a STOMP client exits without sending a DISCONNECT frame, or if it fails, the broker cannot determine if the client is still alive. You can configure a connection Time To Live (TTL) on the broker to automatically close inactive STOMP client connections and clean up resources on the server.

STOMP connections are configured to have a "Time to Live" (TTL) of 1 minute. The means that the broker stops the connection to the STOMP client if it has been idle for more than one minute.

Procedure

  1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

  2. Add the connectionTTL parameter to the URI of the acceptor used for STOMP connections, as shown in the following example: 

    <acceptors>
  <acceptor name="stomp-acceptor">tcp://localhost:61613?protocols=STOMP;connectionTTL=20000</acceptor>
  ...
</acceptors>
    Copy to Clipboard Toggle word wrap

    In the preceding example, any STOMP connection that using the stomp-acceptor will have its TTL set to 20 seconds.

    Note

    Version 1.0 of the STOMP protocol does not contain any heartbeat frame. It is therefore the user’s responsibility to make sure data is sent within the connection TTL or the broker will assume the client is dead and clean up server-side resources. With version 1.1, you can use heart-beats to maintain the life cycle of STOMP connections.

The default TTL for a STOMP connection is one minute. If you do not want clients to be able to specify their own connection TTL, you can set a global parameter on the broker to override values set by clients.

Procedure

  1. Open the <broker_instance_dir>/etc/broker.xml configuration file.

  2. Add the connection-ttl-override attribute and provide a value in milliseconds for the new default. It belongs inside the <core> stanza, as below. 

    <configuration ...>
  ...
  <core ...>
    ...
    <connection-ttl-override>30000</connection-ttl-override>
    ...
  </core>
<configuration>
    Copy to Clipboard Toggle word wrap

    In the preceding example, the default Time to Live (TTL) for a STOMP connection is set to 30 seconds, 30000 milliseconds.

STOMP is mainly a text-orientated protocol. To make it simpler to interoperate with JMS, the STOMP implementation checks for presence of the content-length header to decide how to map a STOMP message to JMS.

Expand
Table 3.3. Mapping a STOMP message to JMS
If you want a STOMP message to map to a …​The message should…​.

JMS TextMessage

Not include a content-length header.

JMS BytesMessage

Include a content-length header.

The same logic applies when mapping a JMS message to STOMP. A STOMP client can confirm the presence of the content-length header to determine the type of the message body (string or bytes).

See the STOMP specification for more information about message headers.

When sending messages and subscribing, STOMP clients typically include a destination header. Destination names are string values, which are mapped to a destination on the broker. In AMQ Broker, these destinations are mapped to addresses and queues.

For more information about the destination frame, see the STOMP specification .

Take for example a STOMP client that sends the following message (headers and body included): 

SEND
destination:/my/stomp/queue

hello queue a
^@
Copy to Clipboard Toggle word wrap

In this case, the broker will forward the message to any queues associated with the address /my/stomp/queue.

For example, when a STOMP client sends a message (by using a SEND frame), the specified destination is mapped to an address.

It works the same way when the client sends a SUBSCRIBE or UNSUBSCRIBE frame, but in this case AMQ Broker maps the destination to a queue. 

SUBSCRIBE
destination: /other/stomp/queue
ack: client

^@
Copy to Clipboard Toggle word wrap

In the preceding example, the broker will map the destination to the queue /other/stomp/queue.

JMS destinations are also mapped to broker addresses and queues. If you want to use STOMP to send messages to JMS destinations, the STOMP destinations must follow the same convention:

  • Send or subscribe to a JMS Queue by prepending the queue name by jms.queue.. For example, to send a message to the orders JMS Queue, the STOMP client must send the frame: 

    SEND
destination:jms.queue.orders
hello queue orders
^@
    Copy to Clipboard Toggle word wrap

  • Send or subscribe to a JMS Topic by prepending the topic name by jms.topic.. For example, to subscribe to the stocks JMS Topic, the STOMP client must send a frame similar to the following: 

    SUBSCRIBE
destination:jms.topic.stocks
^@
    Copy to Clipboard Toggle word wrap
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat