diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 31b71c9157..c93f759129 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -4,9 +4,11 @@ * [Legal Notice](notice.md) * [Preface](preface.md) * [Project Info](project-info.md) +* [Versions](versions.md) * [Messaging Concepts](messaging-concepts.md) * [Architecture](architecture.md) * [Using the Server](using-server.md) +* [Upgrading](upgrading.md) * [Address Model](address-model.md) * [Using JMS](using-jms.md) * [Using Core](using-core.md) @@ -66,4 +68,3 @@ * [Unit Testing](unit-testing.md) * [Troubleshooting and Performance Tuning](perf-tuning.md) * [Configuration Reference](configuration-index.md) -* [Updating Artemis](updating-artemis.md) diff --git a/docs/user-manual/en/management.md b/docs/user-manual/en/management.md index 3b72b07614..809044dc8f 100644 --- a/docs/user-manual/en/management.md +++ b/docs/user-manual/en/management.md @@ -297,7 +297,7 @@ setting `jmx-management-enabled` to `false` in false -#### Role Based Authentication with JMX +#### Role Based Authorisation for JMX Although by default Artemis uses the Java Virtual Machine's `Platform MBeanServer` this is guarded using role based authentication that leverages Artemis's JAAS plugin support. diff --git a/docs/user-manual/en/updating-artemis.md b/docs/user-manual/en/updating-artemis.md deleted file mode 100644 index 9313967189..0000000000 --- a/docs/user-manual/en/updating-artemis.md +++ /dev/null @@ -1,25 +0,0 @@ -# Updating Artemis - -The standard Apache ActiveMQ is runnable out of the box. Just download it, -go into the unzipped ActiveMQ folder and run this command: ./bin/activemq run. -The ActiveMQ Artemis sub project needs an additional step to run the Message Queue. -Before running activemq run you have to create a new message broker instance. -It looks like an overhead at first glance, but becomes very practically -when updating to a new Artemis version for example. -To create a artemis broker cd into the artemis folder and run: `./bin/artemis create $HOME/mybroker` on the command line. - -> **Note** -> -> We recommend choosing a folder different than the downloaded apache-artemis one to separate both from each other. -> This separation allowes you run multiple brokers with the same artemis runtime for example. -> It also simplifies updating to newer versions of Artemis. - -Because of this separation it's very easy to update Artemis. -You just need to cd into the `etc` folder of your created message broker and open the `artemis.profile` file. -It contains a property which is relevant for the update procedure: - - ARTEMIS_HOME='/Users/.../apache-artemis-X.X.X' - -The `ARTEMIS_HOME` property is used to link the broker together with the Artemis runtime. -In case you want to update your broker you can simply download the new version of ActiveMQ Artemis and change the `ARTEMIS_HOME` to the formerly downloaded, newer version. -That's all. There's no need to touch your broker, copy configuration files or stuff like that. \ No newline at end of file diff --git a/docs/user-manual/en/upgrading.md b/docs/user-manual/en/upgrading.md new file mode 100644 index 0000000000..2121c268e7 --- /dev/null +++ b/docs/user-manual/en/upgrading.md @@ -0,0 +1,35 @@ +# Upgrading the Broker + +Apache ActiveMQ 5.x (and previous versions) is runnable out of the box by executing +the command: `./bin/activemq run`. The ActiveMQ Artemis broker follows a different +paradigm where the project distribution serves as the broker "home" and one or more +broker "instances" are created which reference the "home" for resources (e.g. jar files) +which can be safely shared between broker instances. Therefore, an instance of the broker +must be created before it can be run. This may seems like an overhead at first +glance, but it becomes very practical when updating to a new Artemis version for example. + +To create an Artemis broker instance navigate into the Artemis home folder and run: +`./bin/artemis create /path/to/myBrokerInstance` on the command line. + +> **Note** +> +> It's recommended to choose a folder different than the on where Apache Artemis was +> downloaded. This separation allows you run multiple broker instances with the same +> Artemis "home" for example. It also simplifies updating to newer versions of Artemis. + +Because of this separation it's very easy to upgrade Artemis in most cases. Upgrading +may require some specific steps noted in the [versions](versions.md), but the general +process is as follows: + +1. Navigate to the `etc` folder of the broker instance that's being upgraded +1. Open `artemis.profile` (`artemis.profile.cmd` on Windows). It contains a property + which is relevant for the upgrade: + + ``` + ARTEMIS_HOME='/path/to/apache-artemis-version' + ``` + +The `ARTEMIS_HOME` property is used to link the instance with the home. +_In most cases_ the instance can be upgraded to a newer version simply by changing the +value of this property to the location of the new broker home. Please refer to the +aforementioned [versions](versions.md) document for additional upgrade steps (if required). \ No newline at end of file diff --git a/docs/user-manual/en/versions.md b/docs/user-manual/en/versions.md new file mode 100644 index 0000000000..6b8b02b333 --- /dev/null +++ b/docs/user-manual/en/versions.md @@ -0,0 +1,235 @@ +# Versions + +This chapter provides the information for each release: +- A link to the full release notes which includes all issues resolved in the release. +- A brief list of "highlights." +- 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 [Upgrading the Broker](upgrading.md) + chapter in addition to any version-specific upgrade instructions. + +## 2.5.0 + +[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12342127). + +Highlights: +- [Exclusive consumers](address-model.md). +- Equivalent ActiveMQ 5.x Virtual Topic naming abilities. +- SSL Certificate revocation list. +- [Last-value queue](last-value-queues.md) support for OpenWire. +- Support [masked passwords](masking-passwords.md) in bootstrap.xm and login.config +- Configurable [broker plugin](broker-plugins.md) implementation for logging various broker events (i.e. `LoggingActiveMQServerPlugin`). +- Option to use OpenSSL provider for Netty. +- Enable [splitting of broker.xml into multiple files](configuration-index.md). +- Enhanced message count and size metrics for queues. + +## 2.4.0 + +[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12341540). + +Highlights: +- [JMX configuration via XML](management.md) rather than having to use system properties via command line or start script. +- Configuration of [max frame payload length for STOMP web-socket](protocols-interoperability.md). +- Ability to configure HA using JDBC persistence. +- Implement [role-based access control for management objects](management.md). + +#### Upgrading from 2.3.0 + +1. Create `/etc/management.xml`. At the very least, the file must contain this: + ```xml + + ``` + This configures role based authorisation for JMX. Read more in the [Management](management.md) documentation. +1. If configured, remove the Jolokia war file from the `web` element in `/etc/bootstrap.xml`: + ```xml + + ``` + 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: + ```xml + + ``` + _NOTE:_ the Jolokia REST interface URL will now be at `http://:/console/jolokia` + + +## 2.3.0 + +[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12341247). + +Highlights: +- [Web admin console](management-console.md)! +- [Critical Analysis](critical-analysis.md) and deadlock detection on broker +- Support [Netty native kqueue](configuring-transports.md) on Mac. +- [Last-value queue](last-value-queues.md) for AMQP + +#### Upgrading from 2.2.0 + +1. If you desire to deploy the web console then add the following to the `web` element in `/etc/bootstrap.xml`: + ```xml + + ``` + + +## 2.2.0 + +[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12340541). + +Highlights: +- Scheduled messages with the STOMP protocol. +- Support for JNDIReferenceFactory and JNDIStorable. +- Ability to delete queues and addresses when broker.xml changes. +- Client authentication via Kerberos TLS Cipher Suites (RFC 2712). + + +## 2.1.0 + +[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12339963). + +Highlights: +- [Broker plugin support](broker-plugins.md). +- Support [Netty native epoll](configuring-transports.md) on Linux. +- Ability to configure arbitrary security role mappings. +- AMQP performance improvements. + + +## 2.0.0 + +[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12338813). + +Highlights: +- Huge update involving a significant refactoring of the [addressing model](address-model.md) yielding the following benefits: + - Simpler and more flexible XML configuration. + - Support for additional messaging use-cases. + - Eliminates confusing JMS-specific queue naming conventions (i.e. "jms.queue." & "jms.topic." prefixes). +- Pure encoding of messages so protocols like AMQP don't need to convert messages to "core" format unless absolutely necessary. +- ["MAPPED" journal type](persistence.md) for increased performance in certain use-cases. + + +## 1.5.6 + +[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12340547). + +Highlights: +- Bug fixes. + + +## 1.5.5 + +[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12339947). + +Highlights: +- Bug fixes. + + +## 1.5.4 + +[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12339158). + +Highlights: +- Support Oracle12C for JDBC persistence. +- Bug fixes. + + +## 1.5.3 + +[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12339575). + +Highlights: +- Support "byte notation" (e.g. "K", "KB", "Gb", etc.) in broker XML configuration. +- CLI command to recalculate disk sync times. +- Bug fixes. + + +## 1.5.2 + +[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12338833). + +Highlights: +- Support for paging using JDBC. +- Bug fixes. + + +## 1.5.1 + +[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12338661). + +Highlights: +- Support outgoing connections for AMQP. +- Bug fixes. + + +## 1.5.0 + +[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12338118). + +Highlights: +- AMQP performance improvements. +- JUnit rule implementation so messaging resources like brokers can be easily configured in tests. +- Basic CDI integration. +- Store user's password in hash form by default. + + +## 1.4.0 + +[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12336052). + +Highlights: +- "Global" limit for disk usage. +- Detect and reload certain XML configuration changes at runtime. +- MQTT interceptors. +- Support adding/deleting queues via CLI. +- New "browse" security permission for clients who only wish to look at messages. +- Option to populate JMSXUserID. +- "Dual authentication" support to authenticate SSL-based and non-SSL-based clients differently. + + +## 1.3.0 + +[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12328978). + +Highlights: +- Better support of OpenWire features (e.g. reconnect, producer flow-control, optimized acknowledgements) +- SSL keystore reload at runtime. +- Initial support for JDBC persistence. +- Support scheduled messages on last-value queue. + +## 1.2.0 + +[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12333274). + +Highlights: +- Improvements around performance +- OSGi support. +- Support functionality equivalent to all 5.x JAAS login modules including: + - Properties file + - LDAP + - SSL certificate + - "Guest" + + +## 1.1.0 + +[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12332642&projectId=12315920). + +Highlights: +- MQTT support. +- The examples now use the CLI programmatically to create, start, stop, etc. servers reflecting real cases used in + production. +- CLI improvements. There are new tools to compact the journal and additional improvements to the user experience. +- Configurable resource limits. +- Ability to disable server-side message load-balancing. + + +## 1.0.0 + +[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12328953). + +Highlights: +- First release of the [donated code-base](http://mail-archives.apache.org/mod_mbox/activemq-dev/201407.mbox/%3cCAKF+bsovr7Hvn-rMYkb3pF6hoGjx7nuJWzT_Nh8MyC4usRBX9A@mail.gmail.com%3e) as ActiveMQ Artemis! +- Lots of features for parity with ActiveMQ 5.x including: + - OpenWire support + - AMQP 1.0 support + - URL based connections + - Auto-create addresses/queues + - Jolokia integration