Search
SupportConsoleDevelopersStart a trialContact

Chapter 2. Configuring acceptors and connectors in network connections

download PDF

There are two types of connections used in AMQ Broker: network connections and in-VM connections. Network connections are used when the two parties are located in different virtual machines, whether on the same server or physically remote. An in-VM connection is used when the client, whether an application or a server, resides on the same virtual machine as the broker.

Network connections use Netty. Netty is a high-performance, low-level network library that enables network connections to be configured in several different ways; using Java IO or NIO, TCP sockets, SSL/TLS, or tunneling over HTTP or HTTPS. Netty also allows for a single port to be used for all messaging protocols. A broker will automatically detect which protocol is being used and direct the incoming message to the appropriate handler for further processing.

The URI of a network connection determines its type. For example, specifying vm in the URI creates an in-VM connection: 

<acceptor name="in-vm-example">vm://0</acceptor>

Alternatively, specifying tcp in the URI creates a network connection. For example: 

<acceptor name="network-example">tcp://localhost:61617</acceptor>

The sections that follow describe two important configuration elements that are required for network connections and in-VM connections; acceptors and connectors. These sections show how to configure acceptors and connectors for TCP, HTTP, and SSL/TLS network connections, as well as in-VM connections.

2.1. About acceptors

Acceptors define how connections are made to the broker. Each acceptor defines the port and protocols that a client can use to make a connection. A simple acceptor configuration is shown below. 

<acceptors>
   <acceptor name="example-acceptor">tcp://localhost:61617</acceptor>
</acceptors>

Each acceptor element that you define in the broker configuration is contained within a single acceptors element. There is no upper limit to the number of acceptors that you can define for a broker. By default, AMQ Broker includes an acceptor for each supported messaging protocol, as shown below: 

<configuration ...>
   <core ...>
      ...
      <acceptors>
        ...
        <!-- Acceptor for every supported protocol -->
        <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>

2.2. Configuring acceptors

The following example shows how to configure an acceptor.

Procedure

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

  2. In the acceptors element, add a new acceptor element. Specify a protocol, and port on the broker. For example: 

    <acceptors>
   <acceptor name="example-acceptor">tcp://localhost:61617</acceptor>
</acceptors>

    The preceding example defines an acceptor for the TCP protocol. The broker listens on port 61617 for client connections that are using TCP.

  3. Append key-value pairs to the URI defined for the acceptor. Use a semicolon (;) to separate multiple key-value pairs. For example: 

    <acceptor name="example-acceptor">tcp://localhost:61617?sslEnabled=true;key-store-path=</path/to/key_store></acceptor>

    The configuration now defines an acceptor that uses TLS/SSL and defines the path to the required key store.

Additional resources

2.3. About connectors

While acceptors define how a broker accepts connections, connectors are used by clients to define how they can connect to a broker.

A connector is configured on a broker when the broker itself acts as a client. For example:

  • When the broker is bridged to another broker
  • When the broker takes part in a cluster

A simple connector configuration is shown below. 

<connectors>
   <connector name="example-connector">tcp://localhost:61617</connector>
</connectors>

2.4. Configuring connectors

The following example shows how to configure a connector.

Procedure

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

  2. In the connectors element, add a new connector element. Specify a protocol, and port on the broker. For example: 

    <connectors>
   <connector name="example-connector">tcp://localhost:61617</connector>
</connectors>

    The preceding example defines a connector for the TCP protocol. Clients can use the connector configuration to connect to the broker on port 61617 using the TCP protocol. The broker itself can also use this connector for outgoing connections.

  3. Append key-value pairs to the URI defined for the connector. Use a semicolon (;) to separate multiple key-value pairs. For example: 

    <connector name="example-connector">tcp://localhost:61616?tcpNoDelay=true</connector>

    The configuration now defines a connector that sets the value of the tcpNoDelay property to true. Setting the value of this property to true turns off Nagle’s algorithm for the connection. Nagle’s algorithm is an algorithm used to improve the efficiency of TCP connections by delaying transmission of small data packets and consolidating these into large packets.

Additional resources

2.5. Configuring a TCP connection

AMQ Broker uses Netty to provide basic, unencrypted, TCP-based connectivity that can be configured to use blocking Java IO or the newer, non-blocking Java NIO. Java NIO is preferred for better scalability with many concurrent connections. However, using the old IO can sometimes give you better latency than NIO when you are less worried about supporting many thousands of concurrent connections.

If you are running connections across an untrusted network, you should be aware that a TCP network connection is unencrypted. You might want to consider using an SSL or HTTPS configuration to encrypt messages sent over this connection if security is a priority. See Section 5.1, “Securing connections” for more details.

When using a TCP connection, all connections are initiated by the client. The broker does not initiate any connections to the client. This works well with firewall policies that force connections to be initiated from one direction.

For TCP connections, the host and the port of the connector URI define the address used for the connection.

The following example shows how to configure a TCP connection.

Prerequisites

Procedure

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

  2. Add a new acceptor or modify an existing one. In the connection URI, specify tcp as the protocol. Include both an IP address or host name and a port on the broker. For example: 

    <acceptors>
  <acceptor name="tcp-acceptor">tcp://10.10.10.1:61617</acceptor>
  ...
</acceptors>

    Based on the preceding example, the broker accepts TCP communications from clients connecting to port 61617 at the IP address 10.10.10.1.

  3. (Optional) You can configure a connector in a similar way. For example: 

    <connectors>
  <connector name="tcp-connector">tcp://10.10.10.2:61617</connector>
  ...
</connectors>

    The connector in the preceding example is referenced by a client, or even the broker itself, when making a TCP connection to the specified IP and port, 10.10.10.2:61617.

Additional resources

2.6. Configuring an HTTP connection

HTTP connections tunnel packets over the HTTP protocol and are useful in scenarios where firewalls allow only HTTP traffic. AMQ Broker automatically detects if HTTP is being used, so configuring a network connection for HTTP is the same as configuring a connection for TCP.

Prerequisites

Procedure

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

  2. Add a new acceptor or modify an existing one. In the connection URI, specify tcp as the protocol. Include both an IP address or host name and a port on the broker. For example: 

    <acceptors>
  <acceptor name="http-acceptor">tcp://10.10.10.1:80</acceptor>
  ...
</acceptors>

    Based on the preceding example, the broker accepts HTTP communications from clients connecting to port 80 at the IP address 10.10.10.1. The broker automatically detects that the HTTP protocol is in use and communicates with the client accordingly.

  3. (Optional) You can configure a connector in a similar way. For example: 

    <connectors>
  <connector name="http-connector">tcp://10.10.10.2:80</connector>
  ...
</connectors>

    Using the connector shown in the preceding example, a broker creates an outbound HTTP connection on port 80 at the IP address 10.10.10.2.

Additional resources

  • An HTTP connection uses the same configuration parameters as TCP, but it also has some of its own. For details on all of the available configuration options for HTTP connections, see Appendix A, Acceptor and Connector Configuration Parameters.
  • For a full working example that shows how to use HTTP, see the http-transport example that is located in the <install_dir>/examples/features/standard/ directory of your broker installation.

2.7. Configuring secure network connections

You can secure network connections using TLS/SSL. For more information, see Section 5.1, “Securing connections”.

2.8. Configuring an in-VM connection

You can use an in-VM connection when multiple brokers are co-located on the same virtual machine, for example, as part of a high availability (HA) configuration. In-VM connections can also be used by local clients running in the same JVM as the broker.

Prerequisites

Procedure

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

  2. Add a new acceptor or modify an existing one. In the connection URI, specify vm as the protocol. For example: 

    <acceptors>
  <acceptor name="in-vm-acceptor">vm://0</acceptor>
  ...
</acceptors>

    Based on the acceptor in the preceding example, the broker accepts connections from a broker with an ID of 0. The other broker must be running on the same virtual machine.

  3. (Optional) You can configure a connector in a similar way. For example: 

    <connectors>
  <connector name="in-vm-connector">vm://0</connector>
  ...
</connectors>

    The connector in the preceding example defines how a client can establish an in-VM connection to a broker with an ID of 0 that is running on the same virtual machine as the client. The client can be an application or another broker.

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.

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.

© 2024 Red Hat, Inc.