Versions

This chapter provides the following information for each release:

A link to the full release notes which includes all issues resolved in the release.
A brief list of "highlights" when applicable.
If necessary, specific steps required when upgrading from the previous version.

If the upgrade spans multiple versions then the steps from each version need to be followed in order.

Follow the general upgrade procedure outlined in the Upgrading the Broker chapter in addition to any version-specific upgrade instructions outlined here.

1. 2.32.0

Full release notes

1.1. Highlights

Mirrored Core Messages can now be sent on their native format without conversions
Mirror bug fixes and improvements
ActiveMQ Artemis has now adopted more inclusive language definitions.
The examples are now part of its own repository: https://github.com/apache/activemq-artemis-examples/

1.2. Upgrading from 2.31.x

Due to ARTEMIS-4501 MQTT subscription queues will be automatically removed when the corresponding session expires, either based on the session expiry interval passed by an MQTT 5 client or based on the configured defaultMqttSessionExpiryInterval for MQTT 3.x clients or MQTT 5 clients which don’t explicitly pass a session expiry interval.

Prior to this change removing subscription queues relied on the generic auto-delete-* address-settings.

These settings are now no longer required.

Configure defaultMqttSessionExpiryInterval instead.
Due to ARTEMIS-3474 the following configuration elements have changed wherever they occur (e.g. broker.xml, bootstrap.xml, etc.), although all the previous configurations will still be supported for the time being:
- master → primary
- slave → backup
- check-for-live-server → check-for-active-server
- whitelist → allowlist
- blacklist → denylist
Additionally, references to these elements have also changed in the documentation and in management interfaces. Cluster topology information (e.g. returned from the listNetworkTopology) will contain both primary and live entries for nodes functioning as primary servers.

3. 2.31.1

Full release notes

4. 2.31.0

Full release notes

4.1. Highlights

Introduced an interactive shell for running CLI command as well as Bash & ZSH auto-complete support.
Added a CLI cluster verification tool to help monitor broker topologies. Use via the check cluster command.
The queue stat command is now able to to verify the message counts on the entire cluster topology when clustering is in use.
Added AMQP Federation support to broker connections.
MQTT subscription state is now persisted.
Significantly improved the Paging JDBC Persistence.
Converted much of the documentation from MarkDown to AsciiDoc. See ARTEMIS-4383 for more details.
Many other bug fixes and improvements.

4.2. Upgrading from 2.30.0

Due to ARTEMIS-4372 and the introduction of the new Artemis shell feature when you invoke ./artemis it will now start the new shell to navigate through the CLI commands rather than just spitting out the help text.

5. 2.30.0

Full release notes

5.1. Highlights

This is mainly a bug-fix release with a few small improvements and a handful of dependency upgrades. See the release notes for all the details.

6. 2.29.0

Full release notes

6.1. Highlights

This version underwent extensive testing and fixes regarding Large Messages, with a few JIRAs dedicated to this topic. Look on the release notes for more information.

6.2. Upgrading from 2.28.0

Due to ARTEMIS-4151 the default access for MBeans not defined in the 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.

This applies to all MBean access including directly via JMX and via the Jolokia JMX-HTTP bridge.

Due to ARTEMIS-4212 the broker will reject address definitions in 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>

<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)

Due to ARTEMIS-3707 all use of 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.

7. 2.28.0

Full release notes

7.1. Highlights

Bug Fixes and improvements as usual
ARTEMIS-4136 Mirror sync replication
- Mirror now has an option to set sync=true. Blocking operations from clients will wait a round trip on the mirror.
ARTEMIS-4065 Paging Counter Journal Records were removed
- We don’t store page counters records on the journal any longer what should simplify operation and improve performance.

7.2. Upgrading from 2.27.0

Due to ARTEMIS-3871 the naming pattern used for MQTT shared subscription queues has changed. Previously the subscription queue was named according to the subscription name provided in the MQTT 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.

8. 2.27.1

Full release notes

8.1. Highlights

Bug Fixes
AMQP Large Message over Bridges were broken
Rollback of massive transactions would take a long time to process
Improvements to auto-create and auto-delete queues.

9. 2.27.0

Full release notes

9.1. Highlights

2.27.0 Introduced a new upgrade tool to help migrating your instance to a newer version.
The client and broker now use SLF4J for their logging API.
The broker distribution now uses Log4J 2 as its logging implementation.

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.

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 directory.

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 the configuration-file-refresh-period setting in broker.xml 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.

9.3. Manual update

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:

The new <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
The old <instance>/etc/logging.properties JBoss Logging configuration file should be deleted.
Related startup script or profile cleanups are needed: a diff file demonstrating the changes needed since 2.26.0 is available here for *nix or here for Windows.

10. 2.26.0

Full release notes

10.1. Highlights

Bug fixes and improvements

10.2. Upgrading from 2.25.0

Due to ARTEMIS-4006 the artemis-jms-client-all and artemis-jakarta-client-all clients were removed from the lib/client directory in the binary distribution. If you use these libraries they can be found at Maven Central (e.g. here). Please refer to the client class path documentation for more information.
We removed the REST interface from the code-base and documentation. If you still require the REST interface you can access the latest version which is still viable. You can still follow the steps from the previous documentation to build and deploy the interface. However, you should stop using it as it will not be maintained any more.
Due to ARTEMIS-3980 the web content was removed from the binary distribution. We now redirect web requests with the root target to the administration console. To enable this new redirect behavior on current instances you have to update 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.

11. 2.25.0

Full release notes

11.1. Highlights

Improvement on Paging Flow Control
Many other bug fixes and improvements

12. 2.24.0

Full release notes

12.1. Highlights

Streamlined page caches and files are just read into queues without the need of soft caches.

12.2. Upgrading from 2.23.0

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:
1. When login.config is configured with the GuestLoginModule which causes some users to be assigned a specific username and role during the authentication process.
2. When 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.

13. 2.23.1

Full release notes

13.1. Highlights

ARTEMIS-3856 - Failed to change channel state to ReadyForWriting : java.util.ConcurrentModificationException

Versions

2.1.0