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

Full release notes

1.1. Highlights

WebSocket compression is now supported. This compression can be used transparently for AMQP, STOMP, or MQTT when communication is over WebSockets.
The ActiveMQServerMessagePlugin now has a messageMoved() callback.
Core bridge configuration now supports client-id which will make it much easier to identify bridge connections on remote brokers.
The consumer CLI command now supports consuming messages "forever" by specifying -1 for --receive-timeout.
The authentication & authorization caches now have detailed debug logging.
There’s been a handful of updates to broker management:
- The documentation has been improved with more examples for Jolokia and a new sub-section on management method option syntax.
- It’s now possible to pass empty "options" to the management methods that accept them.
- The management methods which return paged results can now return all the results together by specifying -1 for either the page or the pageSize.
- The management method option syntax now supports the NOT_EQUALS operator for greater flexibility with filtering results of management operations.
- Configuration for diverts created via management can now be done via JSON.
The TextFileCertificateLoginModule now supports normalisation of DN property values. See ARTEMIS-5102 for more details

1.2. Upgrading from 2.37.0

Due to ARTEMIS-5096 the web console’s archive (i.e. console.war) will now be uncompressed. This change was necessary in order to remove certain jar files from the archive which were already being distributed in the broker’s main lib directory. Eliminating these duplicate jars will decrease the size of the broker distribution and it also means the console will, in some cases, use updated dependencies and prevent security tools from flagging older jars.
Due to ARTEMIS-5101 the two-way algorithm in the default sensitive string codec used for symmetric password masking is now deprecated. It will continue to work, but it will print a warning to the log. This is the first step in a process to get to eliminate passwords are stored in configuration files except those encoded by strong one-way hashing algorithms. Other use-cases will be pushed toward certificate-based security (i.e. mutual TLS) or something equivalent that requires no password.
Due to ARTEMIS-5085 the parameters retryIntervalMultiplier and maxRetryInterval will now be applied to "initial" connection attempts (i.e. controlled via initialConnectAttempts). This is to fix a bug where these parameters were incorrectly ignored.

2. 2.37.0

Full release notes

2.1. Highlights

The environment variables of the CLI commands other than run is configurable via the artemis-utility.profile file.
The logging configuration of the CLI commands other than run is configurable via the log4j2-utility.properties file.
The run command has been removed from the artemis shell, use the artemis script (artemis.cmd on Windows) to execute it.
A version compatibility on voting (shared nothing replication quorum protocol) was fixed as part of ARTEMIS-4986

The CLI commands other than run will now need to define the environment variables via the artemis-utility.profile file and the logging configuration via the log4j2-utility.properties file. See logging for more information.

3. 2.36.0

Full release notes

3.1. Highlights

Numerous dependency upgrades triggered by integration with GitHub’s Dependabot.
Stability improvement for use-cases involving slower IO devices (e.g. NFS) and the NIO journal via ARTEMIS-4949.
Code optimization in the address manager to decrease CPU utilization and increase broker scalability for use-cases involving a large number of addresses and queues courtesy of ARTEMIS-4814.
Stability improvement for use-cases involving STOMP clients connecting over WebSockets via ARTEMIS-3509.
Lots of internal "code gardening" improvements for developers to make the code-base simpler and more consistent.

4. 2.35.0

Full release notes

4.1. Highlights

5. 2.34.0

Full release notes

5.1. Highlights

5.2. Upgrading from 2.33.0

Due to ARTEMIS-4712 the connection pooling functionality configured via the connectionPool property in login.config is no longer supported in the LDAPLoginModule. The login.config may still use the connectionPool property. No error will be thrown. However, connections will no longer be pooled regardless of the configuration.
Due to ARTEMIS-4498 the web console will now report all internal objects.
- This was done in an attempt to allow administrators to act when things are not working as expected, to get metrics on these objects and allow more transparency for the broker.
- this includes all Openwire Advisor queues and addresses, MQTT internal objects, Cluster Store and Forward (SNF) Queues, Mirror SNF.
- You may want to revisit authorizations if you mean to control access to certain users on the web console.
The CLI operation ./artemis queue stat has its output improved and updated. If you parsed the previous output in scripts you will see differences in the output.
- It is not recommended to parse the output of a CLI Operation. You may use jolokia calls over management instead with proper JSON output.

6. 2.33.0

Full release notes

6.1. Highlights

Support for JSON formatted typed properties on CLI producer command
New CLI command pwd for showing directories related to the current instance
Maven Bill of Materials (BOM) artemis-bom to simplify integration
"FirstMessage" API for scheduled messages
New "view" and "edit" permissions for management operations configurable via security-settings in broker.xml
New sslAutoReload parameter for the embedded web server configured in bootstrap.xml to detect and automatically reload whe SSL stores change on disk
Performance improvements on mirroring and paging
Logging metrics to mitigate the risk of missing WARN or ERROR messages in the log.
Much improved documentation on network isolation (aka split brain)
Pluggable lock manager (aka pluggable quorum voting) out of "experimental" status and ready for general use

6.2. Upgrading from 2.32.0

Due to ARTEMIS-4532 the names of addresses and queues related to MQTT topics and subscriptions respectively may change. This will impact MQTT use-cases if both of the following are true:
1. The broker is configured to use a wildcard syntax which doesn’t match the MQTT wildcard syntax (e.g. the default wildcard syntax).
2. You are using characters from the broker’s wildcard syntax in your MQTT topic name or filter. For example, if you were using the default wildcard syntax and an MQTT topic named 1.0/group/device. The dot (.) character here is part of the broker’s wildcard syntax, and it is being used in the name of an MQTT topic.
  
  In this case the characters from the broker’s wildcard syntax that do not match the characters in the MQTT wildcard syntax will be escaped with a backslash (i.e. \). To avoid this conversion you can configure the broker to use the MQTT wildcard syntax or change the name of the MQTT topic name or filter.
This change will also impact OpenWire JMS consumers which are using # instead of < for wildcard purposes. In previous versions the # character was just passed through when converting from the OpenWire wildcard format to the Core wildcard format. However, now the # character is escaped during conversion. It is a bug for an application to use to use # as a wildcard with the OpenWire JMS client; > is the proper character to use as specified in the ActiveMQ Classic documentation on wildcards.
Due to ARTEMIS-4559 folks embedding the broker and also depending on the artemis-quorum-ri and/or artemis-quorum-api modules and/or using org.apache.activemq.artemis.core.config.ha.DistributedPrimitiveManagerConfiguration will need to use artemis-lockmanager-ri, artemis-lockmanager-api, and org.apache.activemq.artemis.core.config.ha.DistributedLockManagerConfiguration respectively. Previously these were marked as "experimental" in the documentation and were changed strictly in name to clarify their use conceptually. Furthermore, the documentation around high availability and network isolation (i.e. split brain) was refactored significantly to be more clear and comprehensive.

7. 2.32.0

Full release notes

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

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

8. 2.31.2

Full release notes

8.1. Highlights

Bug Fix

9. 2.31.1

Full release notes

9.1. Highlights

Bug Fixes and component upgrades

10. 2.31.0

Full release notes

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

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

11. 2.30.0

Full release notes

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

12. 2.29.0

Full release notes

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

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

13. 2.28.0

Full release notes

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

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

14. 2.27.1

Full release notes

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

15. 2.27.0

Full release notes

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

15.2. Upgrading from 2.26.0

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.

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

16. 2.26.0

Full release notes

16.1. Highlights

Bug fixes and improvements

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

17. 2.25.0

Full release notes

17.1. Highlights

Improvement on Paging Flow Control
Many other bug fixes and improvements

18. 2.24.0

Full release notes

18.1. Highlights

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

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

19. 2.23.1

Full release notes

19.1. Highlights

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

Versions

2.1.0