How to use the OpenMQ Broker separately to Payara Server

Photo of Ondro Mihályi by Ondro Mihályi

Payara Server comes bundled with OpenMQ, which implements the Java Message Service (JMS) standard.

For simple messaging scenarios, it is convenient to use embedded OpenMQ broker, which is available by default. However, this embedded OpenMQ is running inside the JVM instance of Payara Server. This implies that whenever one of them needs to be restarted, the other one gets restarted too.

We've seen reports of messages sometimes getting stuck inside the embedded OpenMQ broker and only getting processed after restarting whole Payara Server. This is not reasonable in more complex use cases with high availability in mind. Most often when clustering is involved, it is worth considering other options of running OpenMQ.


There are 3 modes for GlassFish to use OpenMQ: EMBEDDED, LOCAL and REMOTE. There is some overlap in what is involved with each of these. Section 10-2 of the official GlassFish Server Open Source Edition 4.0 High Availability Administration Guide gives the following definitions:


EMBEDDED  Conventional broker cluster with master broker (default)
Conventional broker cluster of peer brokers
LOCAL Conventional broker cluster with master broker (default)
Conventional broker cluster of peer brokers
Enhanced broker cluster

Conventional broker cluster with master broker
Conventional broker cluster of peer brokers
Enhanced broker cluster

Remote brokers can differ in number from GlassFish instances and can be located on other hosts.



Note that there are 2 more modes: LOCAL and REMOTE.


Both of them provide an additional option to use Enhanced broker cluster, which is more robust and guarantees 100% data availability and recovery at failover.


LOCAL mode means that OpenMQ broker is located on the same host as Payara Server instance. This is easier to manage, but the number of OpenMQ instances needs to be the same as number of Payara Server instances, making it impossible to scale them independently of each other.


REMOTE instances of OpenMQ need to be managed separately from Payara server instances, however, they can differ in number. Adding new instance of Payara server into the cluster does not require additional instance of OpenMQ broker.


A separate remote OpenMQ broker can be started using the imqbrokerd command in the mq/bin directory inside Payara Server installation.


Useful note


Specify -name with the imqbrokerd if there has already been an embedded MQ started. If this is not specified, the default name is used. If the embedded MQ has already been started then this default name gets recorded as being a GlassFish managed broker and cannot be started using the imqbrokerd:


ERROR [B3276]: Starting a GlassFish-managed broker directly using imqbrokerd is not allowed


The remedy is to use the command like the following (which also overrides the default port of 7676):


imqbrokerd -name myBroker -port 1234



To shutdown OpenMQ, use the following command in Payara Server installation:


mq/bin/imqcmd shutdown bkr [-b host:port]


Payara Server installation comes with reasonable defaults to enable wide range of functionality out of the box without additional configuration. This also includes embedded OpenMQ broker, ready to be used immediately. However, LOCAL and REMOTE modes of running OpenMQ are also available. We highly encourage to switch to them in production deployments, especially when high availability is required. To improve reliability with recovery at failover, it is worth to consider using Enhanced broker cluster with LOCAL or REMOTE mode.