This chapter provides the following information for each release:
Highlights:
role-access
or allowlist
of management.xml
is now read only. This is a precautionary measure to ensure no unanticipated MBean deployed with the broker poses a risk. However, this will also impact JVM-specific and platform MBeans as well (e.g. which allow manual garbage collection, “flight recording,” etc.). Write access and general operational access to these MBeans will now have to be manually enabled in management.xml
either by changing the default-access
(not recommended) or specifically configuring a role-access
for the particular MBean in question. Note: this applies to all MBean access including directly via JMX and via the Jolokia JMX-HTTP bridge.broker.xml
which don't specify a routing type, e.g.:<address name="myAddress"/>Such configurations will need to be changed to specify a routing-type, e.g.:
<address name="myAddress"> <anycast/> </address>Or
<address name="myAddress"> <multicast/> </address>If an address without a routing type is configured the broker will throw an exception like this and fail to start:
java.lang.IllegalArgumentException: AMQ229247: Invalid address configuration for 'myAddress'. Address must support multicast and/or anycast. at org.apache.activemq.artemis.core.deployers.impl.FileConfigurationParser.parseAddressConfiguration(FileConfigurationParser.java:1580) at org.apache.activemq.artemis.core.deployers.impl.FileConfigurationParser.parseAddresses(FileConfigurationParser.java:1038) at org.apache.activemq.artemis.core.deployers.impl.FileConfigurationParser.parseMainConfig(FileConfigurationParser.java:804) at org.apache.activemq.artemis.core.config.impl.FileConfiguration.parse(FileConfiguration.java:56) at org.apache.activemq.artemis.core.config.FileDeploymentManager.readConfiguration(FileDeploymentManager.java:81) at org.apache.activemq.artemis.integration.FileBroker.createComponents(FileBroker.java:120) at org.apache.activemq.artemis.cli.commands.Run.execute(Run.java:119) at org.apache.activemq.artemis.cli.Artemis.internalExecute(Artemis.java:212) at org.apache.activemq.artemis.cli.Artemis.execute(Artemis.java:162) at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.base/java.lang.reflect.Method.invoke(Method.java:566) at org.apache.activemq.artemis.boot.Artemis.execute(Artemis.java:144) at org.apache.activemq.artemis.boot.Artemis.main(Artemis.java:61)
javax.transaction.TransactionManager
was removed from the JCA Resource Adapter. However, this rendered the transactionTimeout
activation configuration property useless. Some existing users rely on this behavior so it has been restored and properly deprecated for future removal.Highlights:
SUBSCRIBE
packet. However, MQTT allows the same name to be used across multiple subscriptions whereas queues in the broker must be named uniquely. Now the subscription queue will be named according to the subscription name and topic name so that all subscription queue names will be unique. Before upgrading please ensure all MQTT shared subscriptions are empty. When the subscribers reconnect they will get a new subscription queue. If they are not empty you can move the messages to the new subscription queue administratively.Highlights:
Highlights:
Client applications wanting logging will now need to supply an appropriate SLF4J-supporting logging implementation configured appropriately for their needs. See client application logging for more information plus an example around using Log4J 2.
The broker distribution now includes and configures Log4J 2 as its logging implementation, see logging for more details. If upgrading an existing broker instance rather than creating a new instance, some configuration etc updates will be necessary for the brokers existing instance /etc and /bin files.
You can use the new upgrade helper tool from the newly downloaded broker to refresh various configuration files and scripts for an existing broker instance. The broker.xml and data are left in place as-is.
You should back up your existing broker instance before running the command.
The command can be executed by running ./artemis upgrade <path-to-your-instance>
from the new downloaded broker home.
Note:
Most existing customisations to the old configuration files and scripts will be lost in the process of refreshing the files. As such you should compare the old configuration files with the refreshed ones and then port any missing customisations you may have made as necessary. The upgrade command itself will copy the older files it changes to an old-config-bkp. folder within the instance dir.
Similarly, if you had customised the old logging.properties file you may need to prepare analogous changes for the new log4j2.properties file.
Note also that brokers configuration-file-refresh-period
broker.xml setting no longer covers logging configuration refresh. Log4J 2 has its own configuration reload handling, configured via the monitorInterval
property within the Log4J configuration file itself. The default <instance>/etc/log4j2.properties
file created has a 5 second monitorInterval value set to align with the prior default broker behaviour.
Alternatively, rather than using the upgrade helper command as outlined above, you can instead perform the update manually, following the general upgrading procedure plus the additional steps below:
<instance>/etc/log4j2.properties
file should be created with Log4J 2 configuration. The file used by the “artemis create” CLI command can be downloaded from: log4j2.properties<instance>/etc/logging.properties
JBoss Logging configuration file should be deleted.Highlights:
bootstrap.xml
. Change:<web path="web">to:
<web path="web" rootRedirectLocation="console">If you used to customize the index page or to add custom content in the web folder please refer to the web-server documentation for more information on disabling the redirect and enabling the web content.
Highlights:
Highlights:
Due to ARTEMIS-3851 the queue created for an MQTT 3.x subscriber using CleanSession=1
is now non-durable rather than durable. This may impact security-settings
for MQTT clients which previously only had createDurableQueue
for their role. They will now need createNonDurableQueue
as well. Again, this only has potential impact for MQTT 3.x clients using CleanSession=1
.
Due to ARTEMIS-3892 the username assigned to queues will be based on the validated user rather than just the username submitted by the client application. This will impact use-cases like the following:
login.config
is configured with the GuestLoginModule
which causes some users to be assigned a specific username and role during the authentication process.login.config
is configured with the CertificateLoginModule
which causes users to be assigned a username and role corresponding to the subject DN from their SSL certificate.In these kinds of situations the broker will use this assigned (i.e. validated) username for any queues created with the connection. In the past the queue's username would have been left blank.
Highlights:
Highlights:
Highlights:
producer-window-size
on cluster-connection
was changed to 1MB to mitigate potential OutOfMemoryErrors in environments with with high latency networking.Highlights:
Due to XML schema changes to correct an inaccurate domain name 2 files will need to be updated:
etc/bootstrap.xml
etc/management.xml
In both files change the XML namespace from activemq.org
to activemq.apache.org
, e.g. in bootsrap.xml
use:
<broker xmlns="http://activemq.apache.org/schema">
And in management.xml
use:
<management-context xmlns="http://activemq.apache.org/schema">
If you're using JDBC persistence then due to the changes in ARTEMIS-3679 you'll need to update your database. The column HOLDER_EXPIRATION_TIME
on the NODE_MANAGER_STORE
changed from a TIMESTAMP
to a BIGINT
(or NUMBER(19)
on Oracle). You will have to stop any broker that is accessing that table and either drop it or execute the proper ALTER TABLE
statement for your database. If you drop the table then it will be automatically recreated when broker restarts and repopulated with a new, auto-generated node ID.
If you're using JGroups then due to the changes in ARTEMIS-2413 where JGroups was updated from 3.x to 5.x you will need to update your JGroups configuration. Many of the protocols have changed, and there's no automated tool to bring legacy configurations up to date so please refer to the JGroups documentation for more details on the new configuration. You can find example configurations in the JGroups repository (e.g. tcp.xml
and udp.xml
).
Highlights:
Highlights:
OFF_WITH_REDISTRIBUTION
type.lib/client
directory along with a new example of how to use it in examples/features/standard/queue-jakarta
.Highlights:
Due to ARTEMIS-3367 the default setting for verifyHost
on core connectors has been changed from false
to true
. This means that core clients will now expect the CN
or Subject Alternative Name values of the broker‘s SSL certificate to match the hostname in the client’s URL.
This impacts all core-based clients including core JMS clients and core connections between cluster nodes. Although this is a “breaking” change, not performing hostname verification is a security risk (e.g. due to man-in-the-middle attacks). Enabling it by default aligns core client behavior with industry standards. To deal with this you can do one of the following:
sslEnabled=true
to also use verifyHost=false
. Using this option means that you won't get the extra security of hostname verification, but no certificates will need to change. This essentially restores the previous default behavior.For additional details about please refer to section 3.1 of RFC 2818 “HTTP over TLS”.
Due to ARTEMIS-3117 SSL keystore and truststores are no longer reloaded automatically. Previously an instance of javax.net.ssl.SSLContext
was created for every connection. This would implicitly pick up any changes to the keystore and truststore for any new connection. However, this was grossly inefficient and therefore didn't scale well with lots of connections. The behavior was changed so that just one javax.net.ssl.SSLContext
is created for each acceptor
. However, one can still reload keystores & truststores from disk without restarting the broker. Simply use the reload
management operation on the acceptor
. This is available via JMX, the web console, Jolokia, etc.
Here‘s an example curl
command you can use with Jolokia to invoke the artemis
acceptor’s reload
operation:
curl --user admin:admin --header "Content-Type: application/json" --request POST --data '{"type":"exec", "mbean":"org.apache.activemq.artemis:broker=\"0.0.0.0\",component=acceptors,name=\"artemis\"", "operation":"reload"}' http://localhost:8161/console/jolokia/exec
Of course you'll want to adjust the username & password as well as the broker and acceptor names for your environment.
The “rate” metric for queues was removed from the web console via ARTEMIS-3397. This was a follow-up from ARTEMIS-2909 in 2.16.0 (referenced in the upgrade instructions below). The “rate” metric mistakenly left visible on the web console after it was removed from the management API.
Due to ARTEMIS-3141, ARTEMIS-3128, & ARTEMIS-3175 the data returned for any “list” or “browse” management method which return message data, including those exposed via the web console, will have their return data truncated by default. This is done to avoid adverse conditions with large volumes of message data which could potentially negatively impact broker stability. The management-message-attribute-size-limit
address-setting controls this behavior. If you wish to restore the previous (and potentially dangerous behavior) then you can specify -1
for this. It is 256
by default.
Highlights:
Highlights:
SecurityManager
implementation that supports replicationDue to ARTEMIS-2893 the fundamental way user management was implemented had to change to avoid data integrity issues related to concurrent modification. From a user's perspective two main things changed:
User management is no longer possible using the artemis user
commands when the broker is offline. Of course users are still free to modify the properties files directly in this situation.
The parameters of the artemis user
commands changed. Instead of using something like this:
./artemis user add --user guest --password guest --role admin
Use this instead:
./artemis user add --user-command-user guest --user-command-password guest --role admin
In short, use user-command-user
in lieu of user
and user-command-password
in lieu of password
. Both user
and password
parameters now apply to the connection used to send the command to the broker.
For additional details see ARTEMIS-2893 and ARTEMIS-3010
Due to ARTEMIS-2909 the “rate” metric was removed from the management API for queues. In short, the org.apache.activemq.artemis.core.server.Queue#getRate
method is for slow-consumer detection and is designed for internal use only.
Furthermore, it‘s too opaque to be trusted by a remote user as it only returns the number of message added to the queue since the last time it was called. The problem here is that the user calling it doesn’t know when it was invoked last. Therefore, they could be getting the rate of messages added for the last 5 minutes or the last 5 milliseconds. This can lead to inconsistent and misleading results.
There are three main ways for users to track rates of message production and consumption (in recommended order):
Use a metrics plugin. This is the most feature-rich and flexible way to track broker metrics, although it requires tools (e.g. Prometheus) to store the metrics and display them (e.g. Grafana).
Invoke the getMessageCount()
and getMessagesAdded()
management methods and store the returned values along with the time they were retrieved. A time-series database is a great tool for this job. This is exactly what tools like Prometheus do. That data can then be used to create informative graphs, etc. using tools like Grafana. Of course, one can skip all the tools and just do some simple math to calculate rates based on the last time the counts were retrieved.
Use the broker‘s message counters. Message counters are the broker’s simple way of providing historical information about the queue. They provide similar results to the previous solutions, but with less flexibility since they only track data while the broker is up and there's not really any good options for graphing.
Highlights:
security-settings
and JNDI lookupHighlights:
broker.xml
broker.xml
addressMemoryUsagePercentage
and addressSize
as metricsThis is likely a rare situation, but it's worth mentioning here anyway. Prior to 2.14.0 if you configured a parameter on a queue
in broker.xml
(e.g. max-consumers
) and then later removed that setting the configured value you set would remain. This has changed in 2.14.0 via ARTEMIS-2797. Any value that is not explicitly set in broker.xml
will be set back to either the static default or the dynamic default configured in the address-settings (e.g. via default-max-consumers
in this example). Therefore, ensure any existing queues have all the needed parameters set in broker.xml
values before upgrading.
Highlights:
check
tool for checking the health of a brokerenable-metrics
address settingHierarchicalObjectRepository
, an internal object used to store address and security settingsVersion 2.13.0 added new audit logging which is logged at INFO
level and can be very verbose. The logging.properties
shipped with this new version is set up to filter this out by default. If your logging.properties
isn‘t updated appropriately this audit logging will likely appear in your console and artemis.log
file assuming you’re using a logging configuration close to the default. Add this to your logging.properties
:
# to enable audit change the level to INFO logger.org.apache.activemq.audit.base.level=ERROR logger.org.apache.activemq.audit.base.handlers=AUDIT_FILE logger.org.apache.activemq.audit.base.useParentHandlers=false logger.org.apache.activemq.audit.resource.level=ERROR logger.org.apache.activemq.audit.resource.handlers=AUDIT_FILE logger.org.apache.activemq.audit.resource.useParentHandlers=false logger.org.apache.activemq.audit.message.level=ERROR logger.org.apache.activemq.audit.message.handlers=AUDIT_FILE logger.org.apache.activemq.audit.message.useParentHandlers=false ... #Audit logger handler.AUDIT_FILE=org.jboss.logmanager.handlers.PeriodicRotatingFileHandler handler.AUDIT_FILE.level=INFO handler.AUDIT_FILE.properties=suffix,append,autoFlush,fileName handler.AUDIT_FILE.suffix=.yyyy-MM-dd handler.AUDIT_FILE.append=true handler.AUDIT_FILE.autoFlush=true handler.AUDIT_FILE.fileName=${artemis.instance}/log/audit.log handler.AUDIT_FILE.formatter=AUDIT_PATTERN formatter.AUDIT_PATTERN=org.jboss.logmanager.formatters.PatternFormatter formatter.AUDIT_PATTERN.properties=pattern formatter.AUDIT_PATTERN.pattern=%d [AUDIT](%t) %s%E%n
Highlights:
server
header in STOMP CONNECTED
frame to be disabledacceptor
to more easily identify the acceptor
which has the problem.broker.xml
to find the default connector
URL for commands which require it (e.g. consumer
, producer
, etc.)Highlights:
com.sun.jndi.ldap.read.timeout
in LDAPLoginModule.This was mainly a bug-fix release with a notable dependency change impacting version upgrade.
Due to the WildFly dependency upgrade the broker start scripts/configuration need to be adjusted after upgrading.
Locate this statement in bin/artemis
:
WILDFLY_COMMON="$ARTEMIS_HOME/lib/wildfly-common-1.5.1.Final.jar"
This needs to be replaced with this:
WILDFLY_COMMON="$ARTEMIS_HOME/lib/wildfly-common-1.5.2.Final.jar"
Locate this part of JAVA_ARGS
in etc/artemis.profile.cmd
respectively bin/artemis-service.xml
:
%ARTEMIS_HOME%\lib\wildfly-common-1.5.1.Final.jar
This needs to be replaced with this:
%ARTEMIS_HOME%\lib\wildfly-common-1.5.2.Final.jar
This was a light release. It included a handful of bug fixes, a few improvements, and one major new feature.
Highlights:
This was mainly a bug-fix release with a notable dependency change impacting version upgrade.
Due to the dependency upgrade made on ARTEMIS-2319 the broker start scripts need to be adjusted after upgrading.
Locate this if
statement in bin/artemis
:
if [ -z "$LOG_MANAGER" ] ; then # this is the one found when the server was created LOG_MANAGER="$ARTEMIS_HOME/lib/jboss-logmanager-2.0.3.Final.jar" fi
This needs to be replaced with this block:
if [ -z "$LOG_MANAGER" ] ; then # this is the one found when the server was created LOG_MANAGER="$ARTEMIS_HOME/lib/jboss-logmanager-2.1.10.Final.jar" fi WILDFLY_COMMON=`ls $ARTEMIS_HOME/lib/wildfly-common*jar 2>/dev/null` if [ -z "$WILDFLY_COMMON" ] ; then # this is the one found when the server was created WILDFLY_COMMON="$ARTEMIS_HOME/lib/wildfly-common-1.5.1.Final.jar" fi
Notice that the jboss-logmanager
version has changed and there is also a new wildfly-common
library.
Not much further down there is this line:
-Xbootclasspath/a:"$LOG_MANAGER" \
This line should be changed to be:
-Xbootclasspath/a:"$LOG_MANAGER:$WILDFLY_COMMON" \
Locate this part of JAVA_ARGS
in etc/artemis.profile.cmd
respectively bin/artemis-service.xml
:
-Xbootclasspath/a:%ARTEMIS_HOME%\lib\jboss-logmanager-2.1.10.Final.jar
This needs to be replaced with this:
-Xbootclasspath/a:%ARTEMIS_HOME%\lib\jboss-logmanager-2.1.10.Final.jar;%ARTEMIS_HOME%\lib\wildfly-common-1.5.1.Final.jar
Highlights:
Highlights:
consumersBeforeDispatchStarts
and timeBeforeDispatchStarts
from 5.x.auto-delete-queues-delay
and auto-delete-addresses-delay
Address Settings.default-consumer-window-size
Address Setting.key-store-password
and trust-store-password
in management.xml.JMSXGroupSeq
-1 to close/reset message groups from 5.x.This was mainly a bug-fix release with a few improvements a couple notable new features:
Highlights:
producer
CLI command.This was mainly a bug-fix release with a few improvements but no substantial new features.
This was a bug-fix release with no substantial new features or improvements.
This was a bug-fix release with no substantial new features or improvements.
Highlights:
SASL_EXTERNAL
for AMQP clients.Highlights:
LoggingActiveMQServerPlugin
).sslProvider
URL parameter.acceptor
that needs to be compatible with HornetQ and/or Artemis 1.x clients needs to have anycastPrefix=jms.queue.;multicastPrefix=jms.topic.
in the acceptor
url. This prefix used to be configured automatically behind the scenes when the broker detected these old types of clients, but that broke certain use-cases with no possible work-around. See ARTEMIS-1644 for more details.Highlights:
Create <ARTEMIS_INSTANCE>/etc/management.xml
. At the very least, the file must contain this:
<management-context xmlns="http://activemq.apache.org/schema"/>
This configures role based authorisation for JMX. Read more in the Management documentation.
If configured, remove the Jolokia war file from the web
element in <ARTEMIS_INSTANCE>/etc/bootstrap.xml
:
<app url="jolokia" war="jolokia.war"/>
This is no longer required as the Jolokia REST interface is now integrated into the console web application.
If the following is absent and you desire to deploy the web console then add:
<app url="console" war="console.war"/>
Note: the Jolokia REST interface URL will now be at http://<host>:<port>/console/jolokia
Highlights:
web
element in <ARTEMIS_INSTANCE>/etc/bootstrap.xml
:<app url="console" war="console.war"/>
Highlights:
Highlights:
Highlights:
Highlights:
Highlights:
Highlights:
Highlights:
Highlights:
Highlights:
Highlights:
Highlights:
Highlights:
Highlights:
Highlights:
Highlights: