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.
NOTE: If the upgrade spans multiple versions then the steps from *each* version need to be followed in order.
NOTE: Follow the general upgrade procedure outlined in the xref:upgrading.adoc#upgrading-the-broker[Upgrading the Broker] chapter in addition to any version-specific upgrade instructions outlined here.
This compression can be used transparently for AMQP, STOMP, or MQTT when communication is over WebSockets.
* The xref:broker-plugins.adoc#plugin-support[`ActiveMQServerMessagePlugin`] now has a `messageMoved()` callback.
* xref:core-bridges.adoc#configuring-core-bridges[Core bridge configuration] now supports `client-id` which will make it much easier to identify bridge connections on remote brokers.
* The `consumer` xref:using-cli.adoc[CLI command] now supports consuming messages "forever" by specifying `-1` for `--receive-timeout`.
* The xref:security.adoc#caching-security-operations[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 xref:management.adoc#exposing-jmx-using-jolokia[Jolokia] and a new sub-section on xref:management.adoc#management-method-option-syntax[management method option syntax].
** It's now possible to pass empty "options" to the xref:management.adoc#management-method-option-syntax[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 xref:management.adoc#management-method-option-syntax[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 https://issues.apache.org/jira/browse/ARTEMIS-5102[ARTEMIS-5102] for more details
* Due to https://issues.apache.org/jira/browse/ARTEMIS-5096[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 https://issues.apache.org/jira/browse/ARTEMIS-5101[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 https://issues.apache.org/jira/browse/ARTEMIS-5085[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.
* A version compatibility on voting (shared nothing replication quorum protocol) was fixed as part of https://issues.apache.org/jira/browse/ARTEMIS-4986[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 xref:logging.adoc#logging[logging] for more information.
* Numerous dependency upgrades triggered by integration with https://docs.github.com/en/code-security/getting-started/dependabot-quickstart-guide[GitHub's Dependabot].
* Stability improvement for use-cases involving slower IO devices (e.g. NFS) and the NIO journal via https://issues.apache.org/jira/browse/ARTEMIS-4949[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 https://issues.apache.org/jira/browse/ARTEMIS-4814[ARTEMIS-4814].
* Stability improvement for use-cases involving STOMP clients connecting over WebSockets via https://issues.apache.org/jira/browse/[ARTEMIS-3509].
* Lots of internal "code gardening" improvements for developers to make the code-base simpler and more consistent.
* Due to https://issues.apache.org/jira/browse/ARTEMIS-4712[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 https://issues.apache.org/jira/browse/ARTEMIS-4498[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.
* 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 xref:security.adoc#role-based-security-for-addresses["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
* xref:metrics#optional-metrics[Logging metrics] to mitigate the risk of missing `WARN` or `ERROR` messages in the log.
* Much improved documentation on xref:network-isolation.adoc[network isolation (aka split brain)]
* xref:network-isolation.adoc#pluggable-lock-manager[Pluggable lock manager] (aka pluggable quorum voting) out of "experimental" status and ready for general use
* Due to https://issues.apache.org/jira/browse/ARTEMIS-4532[ARTEMIS-4532] the names of addresses and queues related to MQTT topics and subscriptions respectively may change.
. The broker is configured to use a xref:wildcard-syntax.adoc[wildcard syntax] which _doesn't match_ the xref:mqtt.adoc#wildcard-subscriptions[MQTT wildcard syntax] (e.g. the default wildcard syntax).
. 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 https://activemq.apache.org/components/classic/documentation/wildcards[ActiveMQ Classic documentation on wildcards].
* Due to https://issues.apache.org/jira/browse/ARTEMIS-4559[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.
* Due to https://issues.apache.org/jira/browse/ARTEMIS-4501[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`.
* Due to https://issues.apache.org/jira/browse/ARTEMIS-3474[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:
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.
* Introduced an xref:using-cli.adoc#artemis-shell[interactive shell] for running CLI command as well as xref:using-cli.adoc#bash-and-zsh-auto-complete[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 xref:amqp-broker-connections.adoc#federation[AMQP Federation] support to broker connections.
* xref:mqtt.adoc#persistent-subscriptions[MQTT subscription state is now persisted].
* Significantly improved the Paging JDBC Persistence.
* Converted much of the documentation from MarkDown to AsciiDoc.
See https://issues.apache.org/jira/browse/ARTEMIS-4383[ARTEMIS-4383] for more details.
* Due to https://issues.apache.org/jira/browse/ARTEMIS-4372[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.
* This version underwent extensive testing and fixes regarding Large Messages, with a few JIRAs dedicated to this topic.
Look on the https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12352880&projectId=12315920[release notes] for more information.
=== Upgrading from 2.28.0
* Due to https://issues.apache.org/jira/browse/ARTEMIS-4151[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.
+
NOTE: This applies to all MBean access including directly via JMX and via the Jolokia JMX-HTTP bridge.
* Due to https://issues.apache.org/jira/browse/ARTEMIS-4212[ARTEMIS-4212] the broker will reject address definitions in `broker.xml` which don't specify a routing type, e.g.:
+
[,xml]
----
<address name="myAddress"/>
----
+
Such configurations will need to be changed to specify a routing-type, e.g.:
+
[,xml]
----
<address name="myAddress">
<anycast/>
</address>
----
+
Or
+
[,xml]
----
<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 https://issues.apache.org/jira/browse/ARTEMIS-3707[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.
* 2.27.0 Introduced a new xref:upgrading.adoc#upgrading-tool[upgrade tool] to help migrating your instance to a newer version.
* The client and broker now use https://www.slf4j.org/[SLF4J] for their logging API.
* The broker distribution now uses https://logging.apache.org/log4j/2.x/manual/[Log4J 2] as its logging implementation.
=== 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 xref:logging.adoc#logging-in-a-client-application[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 xref:logging.adoc#logging[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 xref:upgrading.adoc#upgrading-tool[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.
WARNING: 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 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.
=== Manual update
Alternatively, rather than using the upgrade helper command as outlined above, you can instead perform the update manually, following the xref:upgrading.adoc#general-upgrade-procedure[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: https://github.com/apache/activemq-artemis/blob/2.27.0/artemis-cli/src/main/resources/org/apache/activemq/artemis/cli/commands/etc/log4j2.properties[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 link:02-27-00-scripts-profiles.diff[here] for *nix or link:02-27-00-scripts-profiles-windows.diff[here] for Windows.
. Due to https://issues.apache.org/jira/browse/ARTEMIS-4006[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. https://repo1.maven.org/maven2/org/apache/activemq/artemis-jms-client-all/[here]).
Please refer to the xref:client-classpath.adoc#the-client-classpath[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 https://mvnrepository.com/artifact/org.apache.activemq.rest/artemis-rest/2.25.0[latest version] which is still viable.
You can still follow the steps from the https://activemq.apache.org/components/artemis/documentation/2.25.0/rest.html[previous documentation] to build and deploy the interface.
However, you should stop using it as it will not be maintained any more.
. Due to https://issues.apache.org/jira/browse/ARTEMIS-3980[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`.
If you used to customize the index page or to add custom content in the `web` folder please refer to the xref:web-server.adoc#embedded-web-server[web-server documentation] for more information on disabling the redirect and enabling the web content.
* Streamlined page caches and files are just read into queues without the need of soft caches.
=== Upgrading from 2.23.0
. Due to https://issues.apache.org/jira/browse/ARTEMIS-3851[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 https://issues.apache.org/jira/browse/ARTEMIS-3892[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:
.. When `login.config` is configured with the xref:security.adoc#guestloginmodule[`GuestLoginModule`] which causes some users to be assigned a specific username and role during the authentication process.
.. When `login.config` is configured with the xref:security.adoc#certificateloginmodule[`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.
* https://issues.apache.org/jira/browse/ARTEMIS-3856[ARTEMIS-3856] - Failed to change channel state to ReadyForWriting : java.util.ConcurrentModificationException
* The default `producer-window-size` on `cluster-connection` was changed to 1MB to mitigate potential OutOfMemoryErrors in environments with with high latency networking.
* A new set of xref:perf-tools.adoc#performance-tools[performance tools] are now available to evaluate throughput and Response Under Load performance of Artemis
* Diverts now support xref:diverts.adoc#composite-divert[multiple addresses]
* xref:config-reload.adoc#configuration-reload[Runtime configuration reloading] now supports bridges.
* xref:paging.adoc#paging-mode[Paging] can now be configured by message count.
=== Upgrading from 2.20.0
. 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:
. *If you're using xref:persistence.adoc#jdbc-persistence[JDBC persistence]* then due to the changes in https://issues.apache.org/jira/browse/ARTEMIS-3679[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 https://issues.apache.org/jira/browse/ARTEMIS-2413[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 http://jgroups.org/manual5/index.html#protlist[JGroups documentation] for more details on the new configuration.
You can find example configurations in the https://github.com/belaban/JGroups/tree/master/conf[JGroups repository] (e.g. `tcp.xml` and `udp.xml`).
* New environment/system property to set the "key" for masked passwords when using the xref:masking-passwords.adoc#the-default-codec[default codec].
* Ability to disable xref:clusters.adoc#configuring-cluster-connections[message-load-balancing and still allow redistribution] via the new `OFF_WITH_REDISTRIBUTION` type.
* MQTT session state can now be cleaned up automatically to avoid excessive accumulation in situations where client's don't clean up their own sessions.
* Distribute full Jakarta Messaging 3.0 client in the `lib/client` directory along with a new example of how to use it in `examples/features/standard/queue-jakarta`.
. Due to https://issues.apache.org/jira/browse/ARTEMIS-3367[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:
** Update your SSL certificates to use a hostname which matches the hostname in the client's URL.
This is the recommended option with regard to security.
** Update any connector using `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 https://datatracker.ietf.org/doc/html/rfc2818#section-3.1[RFC 2818 "HTTP over TLS"].
. Due to https://issues.apache.org/jira/browse/ARTEMIS-3117[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:
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 https://issues.apache.org/jira/browse/ARTEMIS-3397[ARTEMIS-3397].
This was a follow-up from https://issues.apache.org/jira/browse/ARTEMIS-2909[ARTEMIS-2909] in 2.16.0 (referenced in the <<2-16-0,upgrade instructions below>>).
The "rate" metric mistakenly left visible on the web console after it was removed from the management API.
. Due to https://issues.apache.org/jira/browse/ARTEMIS-3141[ARTEMIS-3141], https://issues.apache.org/jira/browse/ARTEMIS-3128[ARTEMIS-3128], & https://issues.apache.org/jira/browse/ARTEMIS-3175[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.
* A count of addresses and queues is now available from the management API.
* You can now reload the broker's configuration from disk via the management API rather than waiting for the periodic disk scan to pick it up
* Performance improvements on libaio journal.
* New command-line option to transfer messages.
* Performance improvements for the wildcard address manager.
* JDBC datasource property values can now be masked.
* Lots of usability improvements to the Hawtio 2 based web console introduced in 2.16.0
* New management method to create a core bridge using JSON-based configuration input.
* https://blogs.apache.org/activemq/entry/activemq-artemis-embraces-jakarta-ee[Jakarta Messaging 2.0 & 3.0 artifacts for Jakarta EE 8 & 9 respectively].
* xref:amqp-broker-connections.adoc#broker-connections[AMQP Server Connectivity]
* "Basic" xref:security.adoc#basic-security-manager[`SecurityManager` implementation] that supports replication
* Consumer window size support for individual STOMP clients
* Improved JDBC connection management
* New web console based on Hawtio 2
* Performance optimizations (i.e. caching) for authentication and authorization
* Support for admin objects in the JCA resource adapter to facilitate deployment into 3rd-party Java EE application servers
* Ability to prevent an acceptor from automatically starting
=== Upgrading from 2.15.0
. Due to https://issues.apache.org/jira/browse/ARTEMIS-2893[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:
+
[,sh]
----
./artemis user add --user guest --password guest --role admin
----
+
Use this instead:
+
[,sh]
----
./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 https://issues.apache.org/jira/browse/ARTEMIS-2893[ARTEMIS-2893] and https://issues.apache.org/jira/browse/ARTEMIS-3010[ARTEMIS-3010]
. Due to https://issues.apache.org/jira/browse/ARTEMIS-2909[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 xref:metrics.adoc#metrics[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 xref:management.adoc#message-counters[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.
* Ability to "disable" a queue so that messages are not routed to it
* Support JVM GC & thread metrics
* Support for resetting queue properties by unsetting them in `broker.xml`
* Undeploy diverts by removing them from `broker.xml`
* Add `addressMemoryUsagePercentage` and `addressSize` as metrics
=== Upgrading from 2.13.0
This 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.
* Command-line `check` tool for checking the health of a broker
* Support disabling metrics per address via the xref:address-settings.adoc#address-settings[`enable-metrics` address setting]
* Improvements to the xref:logging.adoc#configuring-broker-audit-logging[audit logging]
* Speed optimizations for the `HierarchicalObjectRepository`, an internal object used to store address and security settings
=== Upgrading from 2.12.0
Version 2.13.0 added new xref:logging.adoc#configuring-broker-audit-logging[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.
* Support for xref:configuring-transports.adoc#configuring-netty-socks-proxy[SOCKS proxy]
* Real xref:large-messages.adoc#large-messages[large message] support for AMQP
* xref:undelivered-messages.adoc#automatically-creating-dead-letter-resources[Automatic creation of dead-letter resources] akin to ActiveMQ 5's individual dead-letter strategy
* xref:message-expiry.adoc#configuring-automatic-creation-of-expiry-resources[Automatic creation of expiry resources]
* Improved API for queue creation
* Allow users to override JAVA_ARGS via environment variable
* Reduce heap usage during journal loading during broker start-up
* Allow `server` header in STOMP `CONNECTED` frame to be disabled
* Support disk store used percentage as an exportable metric (e.g. to be monitored by tools like Prometheus, etc.)
* Ability to configure a "https://www.eclipse.org/jetty/javadoc/9.4.26.v20200117/org/eclipse/jetty/server/HttpConfiguration.Customizer.html[customizer]" for the embedded web server
* Improved logging for errors when starting an `acceptor` to more easily identify the `acceptor` which has the problem.
* The CLI will now read the `broker.xml` to find the default `connector` URL for commands which require it (e.g. `consumer`, `producer`, etc.)
* Support xref:retroactive-addresses.adoc#retroactive-addresses[retroactive addresses].
* Support downstream federated xref:federation-queue.adoc#configuring-downstream-federation[queues] and xref:federation-address.adoc#configuring-downstream-federation[addresses].
* Make security manager xref:security.adoc#custom-security-manager[configurable via XML].
* Support pluggable SSL xref:configuring-transports.adoc#configuring-netty-ssl[TrustManagerFactory].
* Add plugin support for federated queues/addresses.
* Support `com.sun.jndi.ldap.read.timeout` in xref:security.adoc#ldaploginmodule[LDAPLoginModule].
This was mainly a bug-fix release with a notable dependency change impacting version upgrade.
=== Upgrading from 2.8.0
Due to the dependency upgrade made on https://issues.apache.org/jira/browse/ARTEMIS-2319[ARTEMIS-2319] the broker start scripts need to be adjusted after upgrading.
==== On *nix
Locate this `if` statement in `bin/artemis`:
----
if [ -z "$LOG_MANAGER" ] ; then
# this is the one found when the server was created
* Add support for delays before deleting addresses and queues via xref:address-settings.adoc#address-settings[`auto-delete-queues-delay` and `auto-delete-addresses-delay` Address Settings].
* Support xref:web-server.adoc#embedded-web-server[logging HTTP access].
* Add a CLI command to purge a queue.
* Support user and role manipulation for PropertiesLoginModule via management interfaces.
* xref:last-value-queues.adoc#last-value-queues[Last-value queue] support for OpenWire.
* Support xref:masking-passwords.adoc#masking-passwords[masked passwords] in bootstrap.xm and login.config
* Configurable xref:broker-plugins.adoc#using-the-loggingactivemqserverplugin[broker plugin] implementation for logging various broker events (i.e. `LoggingActiveMQServerPlugin`).
* Option to use OpenSSL provider for Netty via the xref:configuring-transports.adoc#configuring-netty-ssl[`sslProvider`] URL parameter.
* Enable xref:configuration-index.adoc#configuration-reference[splitting of broker.xml into multiple files].
* Enhanced message count and size metrics for queues.
=== Upgrading from 2.4.0
. Due to changes from https://issues.apache.org/jira/browse/ARTEMIS-1644[ARTEMIS-1644] any `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 https://issues.apache.org/jira/browse/ARTEMIS-1644[ARTEMIS-1644] for more details.
* xref:management.adoc#role-based-authorisation-for-jmx[JMX configuration via XML] rather than having to use system properties via command line or start script.
* Configuration of xref:protocols-interoperability.adoc#stomp-over-web-sockets[max frame payload length for STOMP web-socket].
* Ability to configure HA using JDBC persistence.
* Implement xref:management.adoc#management[role-based access control for management objects].
