ARTEMIS-3010 doc updates
diff --git a/docs/user-manual/en/masking-passwords.md b/docs/user-manual/en/masking-passwords.md
index 028ce6a..1966b4c 100644
--- a/docs/user-manual/en/masking-passwords.md
+++ b/docs/user-manual/en/masking-passwords.md
@@ -70,9 +70,9 @@
- `artemis-users.properties`
-Maksed passwords for `artemis-users.properties` *can* be generated using the
-`mask` command using the `--hash` command-line option. However, we recommend
-using the set of tools provided by the `user` command described below.
+Masked passwords for `artemis-users.properties` *can* be generated using the
+`mask` command using the `--hash` command-line option. However, this is also
+possible using the set of tools provided by the `user` command described below.
## Masking Configuration
@@ -100,10 +100,11 @@
Use the following command from the CLI of the Aremtis *instance* you wish to
add the user/password to. This command will not work from the Artemis home
-used to create the instance. For example:
+used to create the instance, and it will also not work unless the broker has
+been started. For example:
```sh
-./artemis user add --user guest --password guest --role admin
+./artemis user add --user-command-user guest --user-command-password guest --role admin
```
This will use the default codec to perform a "one-way" hash of the password
@@ -114,6 +115,17 @@
not by looking for the syntax `ENC(<hash>)`. The `mask-password` parameter does
not need to be `true` to use hashed passwords here.
+> **Warning**
+>
+> Management and CLI operations to manipulate user & role data are only available
+> when using the `PropertiesLoginModule`.
+>
+> In general, using properties files and broker-centric user management for
+> anything other than very basic use-cases is not recommended. The broker is
+> designed to deal with messages. It's not in the business of managing users,
+> although that functionality is provided at a limited level for convenience. LDAP
+> is recommended for enterprise level production use-cases.
+
### cluster-password
If it is specified in `ENC()` syntax it will be treated as masked, or
diff --git a/docs/user-manual/en/security.md b/docs/user-manual/en/security.md
index ddd32ca..13f2523 100644
--- a/docs/user-manual/en/security.md
+++ b/docs/user-manual/en/security.md
@@ -584,12 +584,15 @@
```
Passwords in `artemis-users.properties` can be hashed. Such passwords should
-follow the syntax `ENC(<hash>)`. Hashed passwords can easily be added to
-`artemis-users.properties` using the `user` CLI command from the Artemis
-*instance*. This command will not work from the Artemis home.
+follow the syntax `ENC(<hash>)`.
+
+Hashed passwords can easily be added to `artemis-users.properties` using the
+`user` CLI command from the Artemis *instance*. This command will not work
+from the Artemis home, and it will also not work unless the broker has been
+started.
```sh
-./artemis user add --user guest --password guest --role admin
+./artemis user add --user-command-user guest --user-command-password guest --role admin
```
This will use the default codec to perform a "one-way" hash of the password
@@ -617,6 +620,12 @@
>
> Management and CLI operations to manipulate user & role data are only available
> when using the `PropertiesLoginModule`.
+>
+> In general, using properties files and broker-centric user management for
+> anything other than very basic use-cases is not recommended. The broker is
+> designed to deal with messages. It's not in the business of managing users,
+> although that functionality is provided at a limited level for convenience. LDAP
+> is recommended for enterprise level production use-cases.
#### LDAPLoginModule
diff --git a/docs/user-manual/en/versions.md b/docs/user-manual/en/versions.md
index 9e4c9f2..9b407e6 100644
--- a/docs/user-manual/en/versions.md
+++ b/docs/user-manual/en/versions.md
@@ -23,6 +23,32 @@
- 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 older versions
+
+Due to [ARTEMIS-2893](https://issues.apache.org/jira/browse/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:
+
+1. 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.
+2. 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 [ARTEMIS-2893](https://issues.apache.org/jira/browse/ARTEMIS-2893)
+ and [ARTEMIS-3010](https://issues.apache.org/jira/browse/ARTEMIS-3010)
+
## 2.15.0
[Full release notes](https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12315920&version=12348568).
