This is an automated email from the ASF dual-hosted git repository.
robbie pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/activemq-artemis.git
The following commit(s) were added to refs/heads/main by this push:
new 97e0a3d7f2 ARTEMIS-4081, ARTEMIS-4020: update versions/update docs
around new upgrade helper tool, and refresh existing manual update step diffs
for subsequent change
97e0a3d7f2 is described below
commit 97e0a3d7f29b03840474f724a79f5879152a09a1
Author: Robbie Gemmell <rob...@apache.org>
AuthorDate: Fri Nov 4 18:09:28 2022 +0000
ARTEMIS-4081, ARTEMIS-4020: update versions/update docs around new upgrade
helper tool, and refresh existing manual update step diffs for subsequent change
---
.../en/02-27-00-scripts-profiles-windows.diff | 18 ++++++++---
docs/user-manual/en/02-27-00-scripts-profiles.diff | 3 +-
docs/user-manual/en/upgrading.md | 26 +++++++++++----
docs/user-manual/en/versions.md | 37 +++++++++++++++++-----
4 files changed, 64 insertions(+), 20 deletions(-)
diff --git a/docs/user-manual/en/02-27-00-scripts-profiles-windows.diff
b/docs/user-manual/en/02-27-00-scripts-profiles-windows.diff
index 8f9a99a987..069e3a55ce 100644
--- a/docs/user-manual/en/02-27-00-scripts-profiles-windows.diff
+++ b/docs/user-manual/en/02-27-00-scripts-profiles-windows.diff
@@ -40,7 +40,7 @@ diff --git a/broker-instance/bin/artemis.cmd
b/broker-instance/bin/artemis.cmd
index 2d39231708..ed7ea68955 100644
--- a/broker-instance/bin/artemis.cmd
+++ b/broker-instance/bin/artemis.cmd
-@@ -48,10 +48,6 @@ rem "Load Profile Config"
+@@ -48,13 +48,9 @@ rem "Load Profile Config"
set ARTEMIS_INSTANCE_ETC="${artemis.instance.etc}"
call %ARTEMIS_INSTANCE_ETC%\artemis.profile.cmd %*
@@ -48,10 +48,15 @@ index 2d39231708..ed7ea68955 100644
-set ARTEMIS_LOGGING_CONF=%ARTEMIS_INSTANCE_ETC_URI%/logging.properties
-set ARTEMIS_LOG_MANAGER=org.jboss.logmanager.LogManager
-
- if not exist "%ARTEMIS_OOME_DUMP%" goto NO_ARTEMIS_OOME_DUMP
+-if not exist "%ARTEMIS_OOME_DUMP%" goto NO_ARTEMIS_OOME_DUMP
++if not exist %ARTEMIS_OOME_DUMP% goto NO_ARTEMIS_OOME_DUMP
rem "Backup the last OOME heap dump"
- move /Y "%ARTEMIS_OOME_DUMP%" "%ARTEMIS_OOME_DUMP%.bkp"
-@@ -66,8 +62,6 @@ set JVM_ARGS=%JVM_ARGS% -Dartemis.home=%ARTEMIS_HOME%
+-move /Y "%ARTEMIS_OOME_DUMP%" "%ARTEMIS_OOME_DUMP%.bkp"
++move /Y %ARTEMIS_OOME_DUMP% %ARTEMIS_OOME_DUMP%.bkp
+
+ :NO_ARTEMIS_OOME_DUMP
+
+@@ -66,11 +62,10 @@ set JVM_ARGS=%JVM_ARGS% -Dartemis.home=%ARTEMIS_HOME%
set JVM_ARGS=%JVM_ARGS% -Dartemis.instance=%ARTEMIS_INSTANCE%
set JVM_ARGS=%JVM_ARGS% -Ddata.dir=%ARTEMIS_DATA_DIR%
set JVM_ARGS=%JVM_ARGS% -Dartemis.instance.etc=%ARTEMIS_INSTANCE_ETC%
@@ -60,6 +65,11 @@ index 2d39231708..ed7ea68955 100644
set JVM_ARGS=%JVM_ARGS%
-Dartemis.default.sensitive.string.codec.key=%ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY%
if not "%DEBUG_ARGS%"=="" set JVM_ARGS=%JVM_ARGS% %DEBUG_ARGS%
++if not "%$JAVA_ARGS_APPEND%"=="" set JVM_ARGS=%JVM_ARGS% %$JAVA_ARGS_APPEND%
+
+ "%_JAVACMD%" %JVM_ARGS% org.apache.activemq.artemis.boot.Artemis %*
+
+
diff --git a/broker-instance/etc/artemis.profile.cmd
b/broker-instance/etc/artemis.profile.cmd
index 5367e34fe4..c4ebbff04a 100644
--- a/broker-instance/etc/artemis.profile.cmd
diff --git a/docs/user-manual/en/02-27-00-scripts-profiles.diff
b/docs/user-manual/en/02-27-00-scripts-profiles.diff
index 9b261be43b..8276a620d2 100644
--- a/docs/user-manual/en/02-27-00-scripts-profiles.diff
+++ b/docs/user-manual/en/02-27-00-scripts-profiles.diff
@@ -43,7 +43,7 @@ index 4f8e2f3b66..5ee4f1e3a0 100755
-Djava.security.auth.login.config="$ARTEMIS_INSTANCE_ETC/login.config" \
$ARTEMIS_CLUSTER_PROPS \
-classpath "$CLASSPATH" \
-@@ -132,8 +112,6 @@ exec "$JAVACMD" \
+@@ -132,8 +112,7 @@ exec "$JAVACMD" \
-Djava.io.tmpdir="$ARTEMIS_INSTANCE/tmp" \
-Ddata.dir="$ARTEMIS_DATA_DIR" \
-Dartemis.instance.etc="$ARTEMIS_INSTANCE_ETC" \
@@ -51,4 +51,5 @@ index 4f8e2f3b66..5ee4f1e3a0 100755
- -Dlogging.configuration="$ARTEMIS_LOGGING_CONF" \
-Dartemis.default.sensitive.string.codec.key="$ARTEMIS_DEFAULT_SENSITIVE_STRING_CODEC_KEY"
\
$DEBUG_ARGS \
++ $JAVA_ARGS_APPEND \
org.apache.activemq.artemis.boot.Artemis "$@"
diff --git a/docs/user-manual/en/upgrading.md b/docs/user-manual/en/upgrading.md
index e82c2eb30f..6736b98f79 100644
--- a/docs/user-manual/en/upgrading.md
+++ b/docs/user-manual/en/upgrading.md
@@ -49,22 +49,34 @@ 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).
-It is also possible to do these steps automatically as it can be seen in the
next section.
+It is also possible to do many of these update steps automatically as can be
seen in the next section.
## Upgrading tool
-An automatic approach can be used to upgrade the instance. You may simply call
`./artemis upgrade <old-instance>`.
+An upgrade helper tool from the new broker download can be used to refresh
various configuration files
+and scripts from an existing broker instance from a prior version, and thus
automate much of work to upgrade
+the instance to use the new version.
+
+> You should back up your existing broker instance before running the command.
```shell
cd $NEW_ARTEMIS_DOWNLOAD/bin/
./artemis upgrade PATH_TO_UPGRADING_INSTANCE
```
-artemis, artemis.profile will be updated to the new version.
+The broker instance `bin/artemis` script and `etc/artemis.profile`(artemis.cmd
and artemis.cmd.profile on Windows)
+will be updated to the new versions, setting its ARTEMIS_HOME to refer to the
new broker version home path. The tool
+will also create the new `<instance>/etc/log4j2.properties` configuration file
if needed (e.g if you are migrating
+from a version prior to 2.27.0), and remove the old
`<instance>/etc/logging.properties` file if present.
-The tool will also update log4j2.properties (if you are migrating from a
version previous to 2.27.0).
+The broker.xml file and data are retained as-is.
> **Note:**
->
->Eventual customizations to your scripts will be lost, however the script will
copy the older version at a created old-config-bkp folder.
-
+>
+> 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.<index> 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.
diff --git a/docs/user-manual/en/versions.md b/docs/user-manual/en/versions.md
index ba94c14714..de85f616c5 100644
--- a/docs/user-manual/en/versions.md
+++ b/docs/user-manual/en/versions.md
@@ -12,7 +12,7 @@ This chapter provides the following information for each
release:
[Full release
notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12352246&projectId=12315920)
Highlights:
-- 2.27.0 Introduced a new upgrade tool to help migrating your instance to a
newer version. Simply use `./artemis upgrade <path-to-your-instance>` from the
new downloaded broker.
+- 2.27.0 Introduced a new [upgrade tool](upgrading.md#upgrading-tool) to help
migrating your instance to a newer version.
- The client and broker now use [SLF4J](https://www.slf4j.org/) for their
logging API.
- The broker distribution now uses [Log4J
2](https://logging.apache.org/log4j/2.x/manual/) as its logging implementation.
@@ -24,20 +24,41 @@ 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](logging.md)
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:
+etc updates will be necessary for the brokers existing instance /etc and /bin
files.
+
+You can use the new [upgrade helper tool](upgrading.md#upgrading-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.<index> 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.
+
+###### 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](upgrading.md#general-upgrade-procedure) plus the additional steps
below:
1. 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](https://github.com/apache/activemq-artemis/blob/2.27.0/artemis-cli/src/main/resources/org/apache/activemq/artemis/cli/commands/etc/log4j2.properties)
2. The old `<instance>/etc/logging.properties` JBoss Logging configuration
file should be deleted.
- 3. Related startup script or profile cleanups are needed: a diff file
demonstrating the removals needed
+ 3. Related startup script or profile cleanups are needed: a diff file
demonstrating the changes needed since 2.26.0
is available [here](02-27-00-scripts-profiles.diff) for \*nix or
[here](02-27-00-scripts-profiles-windows.diff) for Windows.
-Note also that brokers `configuration-file-refresh-period` 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.
-
## 2.26.0
[Full release
notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12352297&projectId=12315920)
