Chapter 2. Configuring acceptors and connectors in network connections
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
-
Open the
<broker_instance_dir>/etc/broker.xml
configuration file. In the
acceptors
element, add a newacceptor
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.
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
- For details on the available configuration options for acceptors and connectors, see Appendix A, Acceptor and Connector Configuration Parameters.
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
-
Open the
<broker_instance_dir>/etc/broker.xml
configuration file. In the
connectors
element, add a newconnector
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.
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 totrue
. Setting the value of this property totrue
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
- For details on the available configuration options for acceptors and connectors, see Appendix A, Acceptor and Connector Configuration Parameters.
- To learn how to configure a broker connector in the AMQ Core Protocol JMS client, see Configuring a broker connector in the AMQ Core Protocol JMS documentation.
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
You should be familiar with configuring acceptors and connectors. For more information, see:
Procedure
-
Open the
<broker_instance_dir>/etc/broker.xml
configuration file. 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 address10.10.10.1
.(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
- For details on the available configuration options for TCP connections, see Appendix A, Acceptor and Connector Configuration Parameters.
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
You should be familiar with configuring acceptors and connectors. For more information, see:
Procedure
-
Open the
<broker_instance_dir>/etc/broker.xml
configuration file. 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 address10.10.10.1
. The broker automatically detects that the HTTP protocol is in use and communicates with the client accordingly.(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 address10.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
You should be familiar with configuring acceptors and connectors. For more information, see:
Procedure
-
Open the
<broker_instance_dir>/etc/broker.xml
configuration file. 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.(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.