activemq-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From clebertsuco...@apache.org
Subject [03/15] activemq-artemis git commit: ARTEMIS-1912 big doc refactor
Date Sat, 09 Jun 2018 05:57:13 GMT
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/security.md
----------------------------------------------------------------------
diff --git a/docs/user-manual/en/security.md b/docs/user-manual/en/security.md
index 2f70701..dfd1a41 100644
--- a/docs/user-manual/en/security.md
+++ b/docs/user-manual/en/security.md
@@ -1,606 +1,755 @@
 # Security
 
-This chapter describes how security works with Apache ActiveMQ Artemis and how you can
-configure it. To disable security completely simply set the
-`security-enabled` property to false in the `broker.xml`
-file.
-
-For performance reasons security is cached and invalidated every so
-long. To change this period set the property
-`security-invalidation-interval`, which is in milliseconds. The default
-is `10000` ms.
-
-To assist in security auditing the `populate-validated-user` option exists. If this is `true` then
-the server will add the name of the validated user to the message using the key `_AMQ_VALIDATED_USER`.
-For JMS and Stomp clients this is mapped to the key `JMSXUserID`. For users authenticated based on
-their SSL certificate this name is the name to which their certificate's DN maps. If `security-enabled`
-is `false` and `populate-validated-user` is `true` then the server will simply use whatever user name
-(if any) the client provides. This option is `false` by default.
+This chapter describes how security works with Apache ActiveMQ Artemis and how
+you can configure it. To disable security completely simply set the
+`security-enabled` property to false in the `broker.xml` file.
+
+For performance reasons security is cached and invalidated every so long. To
+change this period set the property `security-invalidation-interval`, which is
+in milliseconds. The default is `10000` ms.
+
+## Tracking the Validated User
+
+To assist in security auditing the `populate-validated-user` option exists. If
+this is `true` then the server will add the name of the validated user to the
+message using the key `_AMQ_VALIDATED_USER`.  For JMS and Stomp clients this is
+mapped to the key `JMSXUserID`. For users authenticated based on their SSL
+certificate this name is the name to which their certificate's DN maps. If
+`security-enabled` is `false` and `populate-validated-user` is `true` then the
+server will simply use whatever user name (if any) the client provides. This
+option is `false` by default.
 
 ## Role based security for addresses
 
-Apache ActiveMQ Artemis contains a flexible role-based security model for applying
-security to queues, based on their addresses.
+Apache ActiveMQ Artemis contains a flexible role-based security model for
+applying security to queues, based on their addresses.
 
-As explained in [Using Core](using-core.md), Apache ActiveMQ Artemis core consists mainly of sets of queues bound
-to addresses. A message is sent to an address and the server looks up
-the set of queues that are bound to that address, the server then routes
-the message to those set of queues.
+As explained in [Using Core](core.md), Apache ActiveMQ Artemis core consists
+mainly of sets of queues bound to addresses. A message is sent to an address
+and the server looks up the set of queues that are bound to that address, the
+server then routes the message to those set of queues.
 
-Apache ActiveMQ Artemis allows sets of permissions to be defined against the queues
-based on their address. An exact match on the address can be used or a
-wildcard match can be used using the wildcard characters '`#`' and
-'`*`'.
+Apache ActiveMQ Artemis allows sets of permissions to be defined against the
+queues based on their address. An exact match on the address can be used or a
+[wildcard match](wildcard-syntax.md) can be used.
 
-Eight different permissions can be given to the set of queues which
-match the address. Those permissions are:
+Eight different permissions can be given to the set of queues which match the
+address. Those permissions are:
 
--   `createAddress`. This permission allows the user to create an
-    address fitting the `match`.
+- `createAddress`. This permission allows the user to create an address fitting
+  the `match`.
 
--   `deleteAddress`. This permission allows the user to delete an
-    address fitting the `match`.
+- `deleteAddress`. This permission allows the user to delete an address fitting
+  the `match`.
 
--   `createDurableQueue`. This permission allows the user to create a
-    durable queue under matching addresses.
+- `createDurableQueue`. This permission allows the user to create a durable
+  queue under matching addresses.
 
--   `deleteDurableQueue`. This permission allows the user to delete a
-    durable queue under matching addresses.
+- `deleteDurableQueue`. This permission allows the user to delete a durable
+  queue under matching addresses.
 
--   `createNonDurableQueue`. This permission allows the user to create a
-    non-durable queue under matching addresses.
+- `createNonDurableQueue`. This permission allows the user to create a
+  non-durable queue under matching addresses.
 
--   `deleteNonDurableQueue`. This permission allows the user to delete a
-    non-durable queue under matching addresses.
+- `deleteNonDurableQueue`. This permission allows the user to delete a
+  non-durable queue under matching addresses.
 
--   `send`. This permission allows the user to send a message to
-    matching addresses.
+- `send`. This permission allows the user to send a message to matching
+  addresses.
 
--   `consume`. This permission allows the user to consume a message from
-    a queue bound to matching addresses.
+- `consume`. This permission allows the user to consume a message from a queue
+  bound to matching addresses.
 
--   `browse`. This permission allows the user to browse a queue bound to
-    the matching address.
+- `browse`. This permission allows the user to browse a queue bound to the
+  matching address.
 
--   `manage`. This permission allows the user to invoke management
-    operations by sending management messages to the management address.
+- `manage`. This permission allows the user to invoke management operations by
+  sending management messages to the management address.
 
 For each permission, a list of roles who are granted that permission is
-specified. If the user has any of those roles, he/she will be granted
-that permission for that set of addresses.
-
-Let's take a simple example, here's a security block from
-`broker.xml` file:
-
-    <security-setting match="globalqueues.europe.#">
-       <permission type="createDurableQueue" roles="admin"/>
-       <permission type="deleteDurableQueue" roles="admin"/>
-       <permission type="createNonDurableQueue" roles="admin, guest, europe-users"/>
-       <permission type="deleteNonDurableQueue" roles="admin, guest, europe-users"/>
-       <permission type="send" roles="admin, europe-users"/>
-       <permission type="consume" roles="admin, europe-users"/>
-    </security-setting>
-
-The '`#`' character signifies "any sequence of words". Words are
-delimited by the '`.`' character. For a full description of the wildcard
-syntax please see [Understanding the Wildcard Syntax](wildcard-syntax.md).
-The above security block applies to any address
-that starts with the string "globalqueues.europe.":
-
-Only users who have the `admin` role can create or delete durable queues
-bound to an address that starts with the string "globalqueues.europe."
-
-Any users with the roles `admin`, `guest`, or `europe-users` can create
-or delete temporary queues bound to an address that starts with the
-string "globalqueues.europe."
-
-Any users with the roles `admin` or `europe-users` can send messages to
-these addresses or consume messages from queues bound to an address that
-starts with the string "globalqueues.europe."
-
-The mapping between a user and what roles they have is handled by the
-security manager. Apache ActiveMQ Artemis ships with a user manager that reads user
+specified. If the user has any of those roles, he/she will be granted that
+permission for that set of addresses.
+
+Let's take a simple example, here's a security block from `broker.xml` file:
+
+```xml
+<security-setting match="globalqueues.europe.#">
+   <permission type="createDurableQueue" roles="admin"/>
+   <permission type="deleteDurableQueue" roles="admin"/>
+   <permission type="createNonDurableQueue" roles="admin, guest, europe-users"/>
+   <permission type="deleteNonDurableQueue" roles="admin, guest, europe-users"/>
+   <permission type="send" roles="admin, europe-users"/>
+   <permission type="consume" roles="admin, europe-users"/>
+</security-setting>
+```    
+
+Using the default [wildcard syntax](wildcard-syntax.md) the `#` character
+signifies "any sequence of words". Words are delimited by the `.` character.
+Therefore, the above security block applies to any address that starts with the
+string "globalqueues.europe.".
+
+Only users who have the `admin` role can create or delete durable queues bound
+to an address that starts with the string "globalqueues.europe."
+
+Any users with the roles `admin`, `guest`, or `europe-users` can create or
+delete temporary queues bound to an address that starts with the string
+"globalqueues.europe."
+
+Any users with the roles `admin` or `europe-users` can send messages to these
+addresses or consume messages from queues bound to an address that starts with
+the string "globalqueues.europe."
+
+The mapping between a user and what roles they have is handled by the security
+manager. Apache ActiveMQ Artemis ships with a user manager that reads user
 credentials from a file on disk, and can also plug into JAAS or JBoss
 Application Server security.
 
-For more information on configuring the security manager, please see 'Changing the Security Manager'.
+For more information on configuring the security manager, please see 'Changing
+the Security Manager'.
 
-There can be zero or more `security-setting` elements in each xml file.
-Where more than one match applies to a set of addresses the *more
-specific* match takes precedence.
+There can be zero or more `security-setting` elements in each xml file.  Where
+more than one match applies to a set of addresses the *more specific* match
+takes precedence.
 
-Let's look at an example of that, here's another `security-setting`
-block:
+Let's look at an example of that, here's another `security-setting` block:
 
-    <security-setting match="globalqueues.europe.orders.#">
-       <permission type="send" roles="europe-users"/>
-       <permission type="consume" roles="europe-users"/>
-    </security-setting>
+```xml
+<security-setting match="globalqueues.europe.orders.#">
+   <permission type="send" roles="europe-users"/>
+   <permission type="consume" roles="europe-users"/>
+</security-setting>
+```
 
-In this `security-setting` block the match
-'globalqueues.europe.orders.\#' is more specific than the previous match
-'globalqueues.europe.\#'. So any addresses which match
-'globalqueues.europe.orders.\#' will take their security settings *only*
-from the latter security-setting block.
+In this `security-setting` block the match 'globalqueues.europe.orders.\#' is
+more specific than the previous match 'globalqueues.europe.\#'. So any
+addresses which match 'globalqueues.europe.orders.\#' will take their security
+settings *only* from the latter security-setting block.
 
-Note that settings are not inherited from the former block. All the
-settings will be taken from the more specific matching block, so for the
-address 'globalqueues.europe.orders.plastics' the only permissions that
-exist are `send` and `consume` for the role europe-users. The
-permissions `createDurableQueue`, `deleteDurableQueue`,
-`createNonDurableQueue`, `deleteNonDurableQueue` are not inherited from
-the other security-setting block.
+Note that settings are not inherited from the former block. All the settings
+will be taken from the more specific matching block, so for the address
+'globalqueues.europe.orders.plastics' the only permissions that exist are
+`send` and `consume` for the role europe-users. The permissions
+`createDurableQueue`, `deleteDurableQueue`, `createNonDurableQueue`,
+`deleteNonDurableQueue` are not inherited from the other security-setting
+block.
 
-By not inheriting permissions, it allows you to effectively deny
-permissions in more specific security-setting blocks by simply not
-specifying them. Otherwise it would not be possible to deny permissions
-in sub-groups of addresses.
+By not inheriting permissions, it allows you to effectively deny permissions in
+more specific security-setting blocks by simply not specifying them. Otherwise
+it would not be possible to deny permissions in sub-groups of addresses.
 
 ## Security Setting Plugin
 
-Aside from configuring sets of permissions via XML these permissions can alternatively be
-configured via a plugin which implements `org.apache.activemq.artemis.core.server.SecuritySettingPlugin` e.g.:
-
-    <security-settings>
-       <security-setting-plugin class-name="org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin">
-          <setting name="initialContextFactory" value="com.sun.jndi.ldap.LdapCtxFactory"/>
-          <setting name="connectionURL" value="ldap://localhost:1024"/>
-          <setting name="connectionUsername" value="uid=admin,ou=system"/>
-          <setting name="connectionPassword" value="secret"/>
-          <setting name="connectionProtocol" value="s"/>
-          <setting name="authentication" value="simple"/>
-       </security-setting-plugin>
-    </security-settings>
+Aside from configuring sets of permissions via XML these permissions can
+alternatively be configured via a plugin which implements
+`org.apache.activemq.artemis.core.server.SecuritySettingPlugin` e.g.:
+
+```xml
+<security-settings>
+   <security-setting-plugin class-name="org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin">
+      <setting name="initialContextFactory" value="com.sun.jndi.ldap.LdapCtxFactory"/>
+      <setting name="connectionURL" value="ldap://localhost:1024"/>
+      <setting name="connectionUsername" value="uid=admin,ou=system"/>
+      <setting name="connectionPassword" value="secret"/>
+      <setting name="connectionProtocol" value="s"/>
+      <setting name="authentication" value="simple"/>
+   </security-setting-plugin>
+</security-settings>
+```
 
-Most of this configuration is specific to the plugin implementation. However, there are two configuration details that
-will be specified for every implementation:
+Most of this configuration is specific to the plugin implementation. However,
+there are two configuration details that will be specified for every
+implementation:
 
--   `class-name`. This attribute of `security-setting-plugin` indicates the name of the class which implements
-    `org.apache.activemq.artemis.core.server.SecuritySettingPlugin`.
+- `class-name`. This attribute of `security-setting-plugin` indicates the name
+  of the class which implements
+  `org.apache.activemq.artemis.core.server.SecuritySettingPlugin`.
 
--   `setting`. Each of these elements represents a name/value pair that will be passed to the implementation for configuration
-    purposes.
+- `setting`. Each of these elements represents a name/value pair that will be
+  passed to the implementation for configuration purposes.
 
-See the JavaDoc on `org.apache.activemq.artemis.core.server.SecuritySettingPlugin` for further details about the interface
-and what each method is expected to do.
+See the JavaDoc on
+`org.apache.activemq.artemis.core.server.SecuritySettingPlugin` for further
+details about the interface and what each method is expected to do.
 
 ### Available plugins
 
 #### LegacyLDAPSecuritySettingPlugin
 
-This plugin will read the security information that was previously handled by [`LDAPAuthorizationMap`](http://activemq.apache.org/security.html)
-and the [`cachedLDAPAuthorizationMap`](http://activemq.apache.org/cached-ldap-authorization-module.html) in Apache ActiveMQ 5.x
-and turn it into Artemis security settings where possible. The security implementations of ActiveMQ 5.x and Artemis don't
-match perfectly so some translation must occur to achieve near equivalent functionality.
+This plugin will read the security information that was previously handled by
+[`LDAPAuthorizationMap`](http://activemq.apache.org/security.html) and the
+[`cachedLDAPAuthorizationMap`](http://activemq.apache.org/cached-ldap-authorization-module.html)
+in Apache ActiveMQ 5.x and turn it into Artemis security settings where
+possible. The security implementations of ActiveMQ 5.x and Artemis don't match
+perfectly so some translation must occur to achieve near equivalent
+functionality.
 
 Here is an example of the plugin's configuration:
 
-    <security-setting-plugin class-name="org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin">
-       <setting name="initialContextFactory" value="com.sun.jndi.ldap.LdapCtxFactory"/>
-       <setting name="connectionURL" value="ldap://localhost:1024"/>
-       <setting name="connectionUsername" value="uid=admin,ou=system"/>
-       <setting name="connectionPassword" value="secret"/>
-       <setting name="connectionProtocol" value="s"/>
-       <setting name="authentication" value="simple"/>
-    </security-setting-plugin>
-
--   `class-name`. The implementation is `org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin`.
-
--   `initialContextFactory`. The initial context factory used to connect to LDAP. It must always be set to
-    `com.sun.jndi.ldap.LdapCtxFactory` (i.e. the default value).
-
--   `connectionURL`. Specifies the location of the directory server using an ldap URL, `ldap://Host:Port`. You can
-    optionally qualify this URL, by adding a forward slash, `/`, followed by the DN of a particular node in the directory
-    tree. For example, `ldap://ldapserver:10389/ou=system`. The default is `ldap://localhost:1024`.
-
--   `connectionUsername`. The DN of the user that opens the connection to the directory server. For example, `uid=admin,ou=system`.
-    Directory servers generally require clients to present username/password credentials in order to open a connection.
-
--   `connectionPassword`. The password that matches the DN from `connectionUsername`. In the directory server, in the
-    DIT, the password is normally stored as a `userPassword` attribute in the corresponding directory entry.
-
--   `connectionProtocol`. Currently the only supported value is a blank string. In future, this option will allow you to
-    select the Secure Socket Layer (SSL) for the connection to the directory server. Note: this option must be set
-    explicitly to an empty string, because it has no default value.
-
--   `authentication`. Specifies the authentication method used when binding to the LDAP server. Can take either of the
-     values, `simple` (username and password, the default value) or `none` (anonymous). Note: Simple Authentication and
-     Security Layer (SASL) authentication is currently not supported.
-
--   `destinationBase`. Specifies the DN of the node whose children provide the permissions for all destinations. In this
-    case the DN is a literal value (that is, no string substitution is performed on the property value).  For example, a
-    typical value of this property is `ou=destinations,o=ActiveMQ,ou=system` (i.e. the default value).
-
--   `filter`. Specifies an LDAP search filter, which is used when looking up the permissions for any kind of destination.
-    The search filter attempts to match one of the children or descendants of the queue or topic node. The default value
-    is `(cn=*)`.
-
--   `roleAttribute`. Specifies an attribute of the node matched by `filter`, whose value is the DN of a role. Default
-    value is `uniqueMember`.
-
--   `adminPermissionValue`. Specifies a value that matches the `admin` permission. The default value is `admin`.
-
--   `readPermissionValue`. Specifies a value that matches the `read` permission. The default value is `read`.
-
--   `writePermissionValue`. Specifies a value that matches the `write` permission. The default value is `write`.
-
--   `enableListener`. Whether or not to enable a listener that will automatically receive updates made in the LDAP server
-    and update the broker's authorization configuration in real-time. The default value is `true`.
-
-The name of the queue or topic defined in LDAP will serve as the "match" for the security-setting, the permission value
-will be mapped from the ActiveMQ 5.x type to the Artemis type, and the role will be mapped as-is.
-
-ActiveMQ 5.x only has 3 permission types - `read`, `write`, and `admin`. These permission types are described on their
-[website](http://activemq.apache.org/security.html). However, as described previously, ActiveMQ Artemis has 9 permission
-types - `createAddress`, `deleteAddress`, `createDurableQueue`, `deleteDurableQueue`, `createNonDurableQueue`, 
-`deleteNonDurableQueue`, `send`, `consume`, `browse`, and `manage`. Here's how the old types are mapped to the new types:
-
--   `read` - `consume`, `browse`
--   `write` - `send`
--   `admin` - `createAddress`, `deleteAddress`, `createDurableQueue`, `deleteDurableQueue`, `createNonDurableQueue`, 
-    `deleteNonDurableQueue`
-
-As mentioned, there are a few places where a translation was performed to achieve some equivalence.:
-
--   This mapping doesn't include the Artemis `manage` permission type since there is no type analogous for that in ActiveMQ
-    5.x.
+```xml
+<security-setting-plugin class-name="org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin">
+   <setting name="initialContextFactory" value="com.sun.jndi.ldap.LdapCtxFactory"/>
+   <setting name="connectionURL" value="ldap://localhost:1024"/>
+   <setting name="connectionUsername" value="uid=admin,ou=system"/>
+   <setting name="connectionPassword" value="secret"/>
+   <setting name="connectionProtocol" value="s"/>
+   <setting name="authentication" value="simple"/>
+</security-setting-plugin>
+```
 
--   The `admin` permission in ActiveMQ 5.x relates to whether or not the broker will auto-create a destination if
-    it doesn't exist and the user sends a message to it. Artemis automatically allows the automatic creation of a
-    destination if the user has permission to send message to it. Therefore, the plugin will map the `admin` permission
-    to the 4 aforementioned permissions in Artemis.
+- `class-name`. The implementation is
+  `org.apache.activemq.artemis.core.server.impl.LegacyLDAPSecuritySettingPlugin`.
+
+- `initialContextFactory`. The initial context factory used to connect to LDAP.
+  It must always be set to `com.sun.jndi.ldap.LdapCtxFactory` (i.e. the default
+  value).
+
+- `connectionURL`. Specifies the location of the directory server using an ldap
+  URL, `ldap://Host:Port`. You can optionally qualify this URL, by adding a
+  forward slash, `/`, followed by the DN of a particular node in the directory
+  tree. For example, `ldap://ldapserver:10389/ou=system`. The default is
+  `ldap://localhost:1024`.
+
+- `connectionUsername`. The DN of the user that opens the connection to the
+  directory server. For example, `uid=admin,ou=system`.  Directory servers
+  generally require clients to present username/password credentials in order to
+  open a connection.
+
+- `connectionPassword`. The password that matches the DN from
+  `connectionUsername`. In the directory server, in the DIT, the password is
+  normally stored as a `userPassword` attribute in the corresponding directory
+  entry.
+
+- `connectionProtocol`. Currently the only supported value is a blank string.
+  In future, this option will allow you to select the Secure Socket Layer (SSL)
+for the connection to the directory server. **Note:** this option must be set
+explicitly to an empty string, because it has no default value.
+
+- `authentication`. Specifies the authentication method used when binding to
+  the LDAP server. Can take either of the values, `simple` (username and
+password, the default value) or `none` (anonymous). **Note:** Simple Authentication
+and Security Layer (SASL) authentication is currently not supported.
+
+- `destinationBase`. Specifies the DN of the node whose children provide the
+  permissions for all destinations. In this case the DN is a literal value
+  (that is, no string substitution is performed on the property value).  For
+  example, a typical value of this property is
+  `ou=destinations,o=ActiveMQ,ou=system` (i.e. the default value).
+
+- `filter`. Specifies an LDAP search filter, which is used when looking up the
+  permissions for any kind of destination.  The search filter attempts to match
+  one of the children or descendants of the queue or topic node. The default
+  value is `(cn=*)`.
+
+- `roleAttribute`. Specifies an attribute of the node matched by `filter`,
+  whose value is the DN of a role. Default value is `uniqueMember`.
+
+- `adminPermissionValue`. Specifies a value that matches the `admin`
+  permission. The default value is `admin`.
+
+- `readPermissionValue`. Specifies a value that matches the `read` permission.
+  The default value is `read`.
+
+- `writePermissionValue`. Specifies a value that matches the `write`
+  permission. The default value is `write`.
+
+- `enableListener`. Whether or not to enable a listener that will automatically
+  receive updates made in the LDAP server and update the broker's authorization
+  configuration in real-time. The default value is `true`.
+
+The name of the queue or topic defined in LDAP will serve as the "match" for
+the security-setting, the permission value will be mapped from the ActiveMQ 5.x
+type to the Artemis type, and the role will be mapped as-is.
+
+ActiveMQ 5.x only has 3 permission types - `read`, `write`, and `admin`. These
+permission types are described on their
+[website](http://activemq.apache.org/security.html). However, as described
+previously, ActiveMQ Artemis has 9 permission types - `createAddress`,
+`deleteAddress`, `createDurableQueue`, `deleteDurableQueue`,
+`createNonDurableQueue`, `deleteNonDurableQueue`, `send`, `consume`, `browse`,
+and `manage`. Here's how the old types are mapped to the new types:
+
+- `read` - `consume`, `browse`
+- `write` - `send`
+- `admin` - `createAddress`, `deleteAddress`, `createDurableQueue`,
+  `deleteDurableQueue`, `createNonDurableQueue`, `deleteNonDurableQueue`
+
+As mentioned, there are a few places where a translation was performed to
+achieve some equivalence.:
+
+- This mapping doesn't include the Artemis `manage` permission type since there
+  is no type analogous for that in ActiveMQ 5.x.
+
+- The `admin` permission in ActiveMQ 5.x relates to whether or not the broker
+  will auto-create a destination if it doesn't exist and the user sends a
+  message to it. Artemis automatically allows the automatic creation of a
+  destination if the user has permission to send message to it. Therefore, the
+  plugin will map the `admin` permission to the 4 aforementioned permissions in
+  Artemis.
 
 ## Secure Sockets Layer (SSL) Transport
 
-When messaging clients are connected to servers, or servers are connected to other servers (e.g. via bridges) over an
-untrusted network then Apache ActiveMQ Artemis allows that traffic to be encrypted using the Secure Sockets Layer (SSL)
-transport.
+When messaging clients are connected to servers, or servers are connected to
+other servers (e.g. via bridges) over an untrusted network then Apache ActiveMQ
+Artemis allows that traffic to be encrypted using the Secure Sockets Layer
+(SSL) transport.
 
-For more information on configuring the SSL transport, please see [Configuring the Transport](configuring-transports.md).
+For more information on configuring the SSL transport, please see [Configuring
+the Transport](configuring-transports.md).
 
 ## User credentials
 
 Apache ActiveMQ Artemis ships with two security manager implementations:
 
--   The legacy, deprecated `ActiveMQSecurityManager` that reads user credentials, i.e. user names, passwords and role
-information from properties files on the classpath called `artemis-users.properties` and `artemis-roles.properties`.
+- The legacy, deprecated `ActiveMQSecurityManager` that reads user credentials,
+  i.e. user names, passwords and role information from properties files on the
+  classpath called `artemis-users.properties` and `artemis-roles.properties`.
 
--   The flexible, pluggable `ActiveMQJAASSecurityManager` which supports any standard JAAS login module. Artemis ships
-with several login modules which will be discussed further down. This is the default security manager.
+- The flexible, pluggable `ActiveMQJAASSecurityManager` which supports any
+  standard JAAS login module. Artemis ships with several login modules which
+  will be discussed further down. This is the default security manager.
 
 ### JAAS Security Manager
 
-When using the Java Authentication and Authorization Service (JAAS) much of the configuration depends on which login
-module is used. However, there are a few commonalities for every case.
-The first place to look is in `bootstrap.xml`. Here is an example using the `PropertiesLogin` JAAS login
-module which reads user, password, and role information from properties files:
+When using the Java Authentication and Authorization Service (JAAS) much of the
+configuration depends on which login module is used. However, there are a few
+commonalities for every case.  The first place to look is in `bootstrap.xml`.
+Here is an example using the `PropertiesLogin` JAAS login module which reads
+user, password, and role information from properties files:
 
-    <jaas-security domain="PropertiesLogin"/>
+```xml
+<jaas-security domain="PropertiesLogin"/>
+```
 
-No matter what login module you're using, you'll need to specify it here in `bootstrap.xml`. The `domain` attribute
-here refers to the relevant login module entry in `login.config`. For example:
+No matter what login module you're using, you'll need to specify it here in
+`bootstrap.xml`. The `domain` attribute here refers to the relevant login
+module entry in `login.config`. For example:
 
-    PropertiesLogin {
-        org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule required
-            debug=true
-            org.apache.activemq.jaas.properties.user="artemis-users.properties"
-            org.apache.activemq.jaas.properties.role="artemis-roles.properties";
-    };
+```
+PropertiesLogin {
+    org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule required
+        debug=true
+        org.apache.activemq.jaas.properties.user="artemis-users.properties"
+        org.apache.activemq.jaas.properties.role="artemis-roles.properties";
+};
+```
 
-The `login.config` file is a standard JAAS configuration file. You can read more about this file on
-[Oracle's website](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jgss/tutorials/LoginConfigFile.html).
+The `login.config` file is a standard JAAS configuration file. You can read
+more about this file on [Oracle's
+website](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jgss/tutorials/LoginConfigFile.html).
 In short, the file defines:
 
--   an alias for an entry (e.g. `PropertiesLogin`)
+- an alias for an entry (e.g. `PropertiesLogin`)
 
--   the implementation class for the login module (e.g. `org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule`)
+- the implementation class for the login module (e.g.
+  `org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule`)
 
--   a flag which indicates whether the success of the login module is `required`, `requisite`, `sufficient`, or `optional`
-(see more details on these flags in the [JavaDoc](https://docs.oracle.com/javase/8/docs/api/javax/security/auth/login/Configuration.html)
+- a flag which indicates whether the success of the login module is `required`,
+  `requisite`, `sufficient`, or `optional` (see more details on these flags in
+  the
+  [JavaDoc](https://docs.oracle.com/javase/8/docs/api/javax/security/auth/login/Configuration.html)
 
--   a list of configuration options specific to the login module implementation
+- a list of configuration options specific to the login module implementation
 
-By default, the location and name of `login.config` is specified on the Artemis command-line which is set by
-`etc/artemis.profile` on linux and `etc\artemis.profile.cmd` on Windows.
+By default, the location and name of `login.config` is specified on the Artemis
+command-line which is set by `etc/artemis.profile` on linux and 
+`etc\artemis.profile.cmd` on Windows.
 
 #### Dual Authentication
 
-The JAAS Security Manager also supports another configuration parameter - `certificate-domain`. This is useful when you
-want to authenticate clients connecting with SSL connections based on their SSL certificates (e.g. using the `CertificateLoginModule`
-discussed below) but you still want to authenticate clients connecting with non-SSL connections with, e.g., username and
-password. Here's an example of what would go in `bootstrap.xml`:
+The JAAS Security Manager also supports another configuration parameter -
+`certificate-domain`. This is useful when you want to authenticate clients
+connecting with SSL connections based on their SSL certificates (e.g. using the
+`CertificateLoginModule` discussed below) but you still want to authenticate
+clients connecting with non-SSL connections with, e.g., username and password.
+Here's an example of what would go in `bootstrap.xml`:
 
-    <jaas-security domain="PropertiesLogin" certificate-domain="CertLogin"/>
+```xml
+<jaas-security domain="PropertiesLogin" certificate-domain="CertLogin"/>
+```
 
 And here's the corresponding `login.config`:
 
-    PropertiesLogin {
-       org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule required
-           debug=false
-           org.apache.activemq.jaas.properties.user="artemis-users.properties"
-           org.apache.activemq.jaas.properties.role="artemis-roles.properties";
-    };
-
-    CertLogin {
-       org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule required
-           debug=true
-           org.apache.activemq.jaas.textfiledn.user="cert-users.properties"
-           org.apache.activemq.jaas.textfiledn.role="cert-roles.properties";
-    };
+```
+PropertiesLogin {
+   org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule required
+       debug=false
+       org.apache.activemq.jaas.properties.user="artemis-users.properties"
+       org.apache.activemq.jaas.properties.role="artemis-roles.properties";
+};
+
+CertLogin {
+   org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule required
+       debug=true
+       org.apache.activemq.jaas.textfiledn.user="cert-users.properties"
+       org.apache.activemq.jaas.textfiledn.role="cert-roles.properties";
+};
+```
 
-When the broker is configured this way then any client connecting with SSL and a client certificate will be authenticated
-using `CertLogin` and any client connecting without SSL will be authenticated using `PropertiesLogin`.
+When the broker is configured this way then any client connecting with SSL and
+a client certificate will be authenticated using `CertLogin` and any client
+connecting without SSL will be authenticated using `PropertiesLogin`.
 
 ### JAAS Login Modules
 
 #### GuestLoginModule
-Allows users without credentials (and, depending on how it is configured, possibly also users with invalid credentials)
-to access the broker. Normally, the guest login module is chained with another login module, such as a properties login
-module. It is implemented by `org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule`.
 
--   `org.apache.activemq.jaas.guest.user` - the user name to assign; default is "guest"
+Allows users without credentials (and, depending on how it is configured,
+possibly also users with invalid credentials) to access the broker. Normally,
+the guest login module is chained with another login module, such as a
+properties login module. It is implemented by
+`org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule`.
 
--   `org.apache.activemq.jaas.guest.role` - the role name to assign; default is "guests"
+- `org.apache.activemq.jaas.guest.user` - the user name to assign; default is "guest"
 
--   `credentialsInvalidate` - boolean flag; if `true`, reject login requests that include a password (i.e. guest login
-succeeds only when the user does not provide a password); default is `false`
+- `org.apache.activemq.jaas.guest.role` - the role name to assign; default is "guests"
 
--   `debug` - boolean flag; if `true`, enable debugging; this is used only for testing or debugging; normally, it
-should be set to `false`, or omitted; default is `false`
+- `credentialsInvalidate` - boolean flag; if `true`, reject login requests that
+  include a password (i.e. guest login succeeds only when the user does not
+  provide a password); default is `false`
+
+- `debug` - boolean flag; if `true`, enable debugging; this is used only for
+  testing or debugging; normally, it should be set to `false`, or omitted;
+  default is `false`
 
 There are two basic use cases for the guest login module, as follows:
 
--   Guests with no credentials or invalid credentials.
+- Guests with no credentials or invalid credentials.
 
--   Guests with no credentials only.
+- Guests with no credentials only.
 
-The following snippet shows how to configure a JAAS login entry for the use case where users with no credentials or
-invalid credentials are logged in as guests. In this example, the guest login module is used in combination with the
+The following snippet shows how to configure a JAAS login entry for the use
+case where users with no credentials or invalid credentials are logged in as
+guests. In this example, the guest login module is used in combination with the
 properties login module.
 
-    activemq-domain {
-      org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule sufficient
-          debug=true
-          org.apache.activemq.jaas.properties.user="artemis-users.properties"
-          org.apache.activemq.jaas.properties.role="artemis-roles.properties";
-
-      org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule sufficient
-          debug=true
-          org.apache.activemq.jaas.guest.user="anyone"
-          org.apache.activemq.jaas.guest.role="restricted";
-    };
+```
+activemq-domain {
+  org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule sufficient
+      debug=true
+      org.apache.activemq.jaas.properties.user="artemis-users.properties"
+      org.apache.activemq.jaas.properties.role="artemis-roles.properties";
+
+  org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule sufficient
+      debug=true
+      org.apache.activemq.jaas.guest.user="anyone"
+      org.apache.activemq.jaas.guest.role="restricted";
+};
+```
 
 Depending on the user login data, authentication proceeds as follows:
 
--   User logs in with a valid password — the properties login module successfully authenticates the user and returns
-    immediately. The guest login module is not invoked.
-
--   User logs in with an invalid password — the properties login module fails to authenticate the user, and authentication
-    proceeds to the guest login module. The guest login module successfully authenticates the user and returns the guest principal.
+- User logs in with a valid password — the properties login module successfully
+  authenticates the user and returns immediately. The guest login module is not
+  invoked.
 
--   User logs in with a blank password — the properties login module fails to authenticate the user, and authentication
-    proceeds to the guest login module. The guest login module successfully authenticates the user and returns the guest principal.
+- User logs in with an invalid password — the properties login module fails to
+  authenticate the user, and authentication proceeds to the guest login module.
+  The guest login module successfully authenticates the user and returns the
+  guest principal.
 
-The following snipped shows how to configure a JAAS login entry for the use case where only those users with no
-credentials are logged in as guests. To support this use case, you must set the credentialsInvalidate option to true in
-the configuration of the guest login module. You should also note that, compared with the preceding example, the order
-of the login modules is reversed and the flag attached to the properties login module is changed to requisite.
+- User logs in with a blank password — the properties login module fails to
+  authenticate the user, and authentication proceeds to the guest login module.
+  The guest login module successfully authenticates the user and returns the
+  guest principal.
 
-    activemq-guest-when-no-creds-only-domain {
-        org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule sufficient
-            debug=true
-           credentialsInvalidate=true
-           org.apache.activemq.jaas.guest.user="guest"
-           org.apache.activemq.jaas.guest.role="guests";
+The following snipped shows how to configure a JAAS login entry for the use
+case where only those users with no credentials are logged in as guests. To
+support this use case, you must set the credentialsInvalidate option to true in
+the configuration of the guest login module. You should also note that,
+compared with the preceding example, the order of the login modules is reversed
+and the flag attached to the properties login module is changed to requisite.
 
-        org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule requisite
-            debug=true
-            org.apache.activemq.jaas.properties.user="artemis-users.properties"
-            org.apache.activemq.jaas.properties.role="artemis-roles.properties";
-    };
+```
+activemq-guest-when-no-creds-only-domain {
+    org.apache.activemq.artemis.spi.core.security.jaas.GuestLoginModule sufficient
+        debug=true
+       credentialsInvalidate=true
+       org.apache.activemq.jaas.guest.user="guest"
+       org.apache.activemq.jaas.guest.role="guests";
+
+    org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule requisite
+        debug=true
+        org.apache.activemq.jaas.properties.user="artemis-users.properties"
+        org.apache.activemq.jaas.properties.role="artemis-roles.properties";
+};
+```
 
 Depending on the user login data, authentication proceeds as follows:
 
--   User logs in with a valid password — the guest login module fails to authenticate the user (because the user has
-    presented a password while the credentialsInvalidate option is enabled) and authentication proceeds to the properties
-    login module. The properties login module successfully authenticates the user and returns.
+- User logs in with a valid password — the guest login module fails to
+  authenticate the user (because the user has presented a password while the
+  credentialsInvalidate option is enabled) and authentication proceeds to the
+  properties login module. The properties login module successfully authenticates
+  the user and returns.
 
--   User logs in with an invalid password — the guest login module fails to authenticate the user and authentication proceeds
-    to the properties login module. The properties login module also fails to authenticate the user. The nett result is
-    authentication failure.
+- User logs in with an invalid password — the guest login module fails to
+  authenticate the user and authentication proceeds to the properties login
+  module. The properties login module also fails to authenticate the user. The
+  net result is authentication failure.
 
--   User logs in with a blank password — the guest login module successfully authenticates the user and returns immediately.
-    The properties login module is not invoked.
+- User logs in with a blank password — the guest login module successfully
+  authenticates the user and returns immediately.  The properties login module
+  is not invoked.
 
 #### PropertiesLoginModule
-The JAAS properties login module provides a simple store of authentication data, where the relevant user data is stored
-in a pair of flat files. This is convenient for demonstrations and testing, but for an enterprise system, the integration
-with LDAP is preferable. It is implemented by `org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule`.
-
--   `org.apache.activemq.jaas.properties.user` - the path to the file which contains user and password properties
-
--   `org.apache.activemq.jaas.properties.role` - the path to the file which contains user and role properties
-
--   `reload` - boolean flag; whether or not to reload the properties files when a modification occurs; default is `false`
-
--   `debug` - boolean flag; if `true`, enable debugging; this is used only for testing or debugging; normally, it
-should be set to `false`, or omitted; default is `false`
-
-In the context of the properties login module, the `artemis-users.properties` file consists of a list of properties of the
-form, `UserName=Password`. For example, to define the users `system`, `user`, and `guest`, you could create a file like
-the following:
-
-    system=manager
-    user=password
-    guest=password
-
-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, e.g.:
+The JAAS properties login module provides a simple store of authentication
+data, where the relevant user data is stored in a pair of flat files. This is
+convenient for demonstrations and testing, but for an enterprise system, the
+integration with LDAP is preferable. It is implemented by
+`org.apache.activemq.artemis.spi.core.security.jaas.PropertiesLoginModule`.
+
+- `org.apache.activemq.jaas.properties.user` - the path to the file which
+  contains user and password properties
+
+- `org.apache.activemq.jaas.properties.role` - the path to the file which
+  contains user and role properties
+
+- `reload` - boolean flag; whether or not to reload the properties files when a
+  modification occurs; default is `false`
+
+- `debug` - boolean flag; if `true`, enable debugging; this is used only for
+  testing or debugging; normally, it should be set to `false`, or omitted;
+  default is `false`
+
+In the context of the properties login module, the `artemis-users.properties`
+file consists of a list of properties of the form, `UserName=Password`. For
+example, to define the users `system`, `user`, and `guest`, you could create a
+file like the following:
+
+```properties
+system=manager
+user=password
+guest=password
+```
 
+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, e.g.:
 
 ```sh
-    ./artemis user add --username guest --password guest --role admin
+./artemis user add --username guest --password guest --role admin
 ```
 
-This will use the default `org.apache.activemq.artemis.utils.DefaultSensitiveStringCodec` to perform a "one-way" hash of
-the password and alter both the `artemis-users.properties` and `artemis-roles.properties` files with the specified values. 
+This will use the default
+`org.apache.activemq.artemis.utils.DefaultSensitiveStringCodec` to perform a
+"one-way" hash of the password and alter both the `artemis-users.properties`
+and `artemis-roles.properties` files with the specified values. 
 
-The `artemis-roles.properties` file consists of a list of properties of the form, `Role=UserList`, where UserList is a
-comma-separated list of users. For example, to define the roles `admins`, `users`, and `guests`, you could create a file
-like the following:
+The `artemis-roles.properties` file consists of a list of properties of the
+form, `Role=UserList`, where UserList is a comma-separated list of users. For
+example, to define the roles `admins`, `users`, and `guests`, you could create
+a file like the following:
 
-    admins=system
-    users=system,user
-    guests=guest
+```properties
+admins=system
+users=system,user
+guests=guest
+```
 
 #### LDAPLoginModule
-The LDAP login module enables you to perform authentication and authorization by checking the incoming credentials against
-user data stored in a central X.500 directory server. For systems that already have an X.500 directory server in place,
-this means that you can rapidly integrate ActiveMQ Artemis with the existing security database and user accounts can be
-managed using the X.500 system. It is implemented by `org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule`.
-
--   `initialContextFactory` - must always be set to `com.sun.jndi.ldap.LdapCtxFactory`
-
--   `connectionURL` - specify the location of the directory server using an ldap URL, ldap://Host:Port. You can
-    optionally qualify this URL, by adding a forward slash, `/`, followed by the DN of a particular node in the directory
-    tree. For example, ldap://ldapserver:10389/ou=system.
 
--   `authentication` - specifies the authentication method used when binding to the LDAP server. Can take either of
-    the values, `simple` (username and password), `GSSAPI` (Kerberos SASL) or `none` (anonymous).
-
--   `connectionUsername` - the DN of the user that opens the connection to the directory server. For example,
-    `uid=admin,ou=system`. Directory servers generally require clients to present username/password credentials in order
-    to open a connection.
-
--   `connectionPassword` - the password that matches the DN from `connectionUsername`. In the directory server,
-    in the DIT, the password is normally stored as a `userPassword` attribute in the corresponding directory entry.
-
--   `saslLoginConfigScope` - the scope in JAAS configuration (login.config) to use to obtain Kerberos initiator credentials
-    when the `authentication` method is SASL `GSSAPI`. The default value is `broker-sasl-gssapi`.
-
--   `connectionProtocol` - currently, the only supported value is a blank string. In future, this option will allow
-    you to select the Secure Socket Layer (SSL) for the connection to the directory server. This option must be set
-    explicitly to an empty string, because it has no default value.
-
--   `userBase` - selects a particular subtree of the DIT to search for user entries. The subtree is specified by a
-    DN, which specifes the base node of the subtree. For example, by setting this option to `ou=User,ou=ActiveMQ,ou=system`,
-    the search for user entries is restricted to the subtree beneath the `ou=User,ou=ActiveMQ,ou=system` node.
-
--   `userSearchMatching` - specifies an LDAP search filter, which is applied to the subtree selected by `userBase`.
-    Before passing to the LDAP search operation, the string value you provide here is subjected to string substitution,
-    as implemented by the `java.text.MessageFormat` class. Essentially, this means that the special string, `{0}`, is
-    substituted by the username, as extracted from the incoming client credentials.
-
-    After substitution, the string is interpreted as an LDAP search filter, where the LDAP search filter syntax is
-    defined by the IETF standard, RFC 2254. A short introduction to the search filter syntax is available from Oracle's
-    JNDI tutorial, [Search Filters](https://docs.oracle.com/javase/jndi/tutorial/basics/directory/filter.html).
-
-    For example, if this option is set to `(uid={0})` and the received username is `jdoe`, the search filter becomes
-    `(uid=jdoe)` after string substitution. If the resulting search filter is applied to the subtree selected by the
-    user base, `ou=User,ou=ActiveMQ,ou=system`, it would match the entry, `uid=jdoe,ou=User,ou=ActiveMQ,ou=system`
-    (and possibly more deeply nested entries, depending on the specified search depth—see the `userSearchSubtree` option).
-
--   `userSearchSubtree` - specify the search depth for user entries, relative to the node specified by `userBase`.
-    This option is a boolean. `false` indicates it will try to match one of the child entries of the `userBase` node
-    (maps to `javax.naming.directory.SearchControls.ONELEVEL_SCOPE`). `true` indicates it will try to match any entry
-    belonging to the subtree of the `userBase` node (maps to `javax.naming.directory.SearchControls.SUBTREE_SCOPE`).
-
--   `userRoleName` - specifies the name of the multi-valued attribute of the user entry that contains a list of
-    role names for the user (where the role names are interpreted as group names by the broker's authorization plug-in).
-    If you omit this option, no role names are extracted from the user entry.
-
--   `roleBase` - if you want to store role data directly in the directory server, you can use a combination of role
-    options (`roleBase`, `roleSearchMatching`, `roleSearchSubtree`, and `roleName`) as an alternative to (or in addition
-    to) specifying the `userRoleName` option. This option selects a particular subtree of the DIT to search for role/group
-    entries. The subtree is specified by a DN, which specifes the base node of the subtree. For example, by setting this
-    option to `ou=Group,ou=ActiveMQ,ou=system`, the search for role/group entries is restricted to the subtree beneath
-    the `ou=Group,ou=ActiveMQ,ou=system` node.
-
--   `roleName` - specifies the attribute type of the role entry that contains the name of the role/group (e.g. C, O,
-    OU, etc.). If you omit this option the full DN of the role is used.
-
--   `roleSearchMatching` - specifies an LDAP search filter, which is applied to the subtree selected by `roleBase`.
-    This works in a similar manner to the `userSearchMatching` option, except that it supports two substitution strings,
-    as follows:
-
-    -   `{0}` - substitutes the full DN of the matched user entry (that is, the result of the user search). For
-        example, for the user, `jdoe`, the substituted string could be `uid=jdoe,ou=User,ou=ActiveMQ,ou=system`.
-
-    -   `{1}` - substitutes the received username. For example, `jdoe`.
-
-    For example, if this option is set to `(member=uid={1})` and the received username is `jdoe`, the search filter
-    becomes `(member=uid=jdoe)` after string substitution (assuming ApacheDS search filter syntax). If the resulting
-    search filter is applied to the subtree selected by the role base, `ou=Group,ou=ActiveMQ,ou=system`, it matches all
-    role entries that have a `member` attribute equal to `uid=jdoe` (the value of a `member` attribute is a DN).
-
-    This option must always be set to enable role searching because it has no default value. Leaving it unset disables
-    role searching and the role information must come from `userRoleName`.
-
-    If you use OpenLDAP, the syntax of the search filter is `(member:=uid=jdoe)`.
-
--   `roleSearchSubtree` - specify the search depth for role entries, relative to the node specified by `roleBase`.
-    This option can take boolean values, as follows:
-
-    -   `false` (default) - try to match one of the child entries of the roleBase node (maps to
-        `javax.naming.directory.SearchControls.ONELEVEL_SCOPE`).
-
-    -   `true` — try to match any entry belonging to the subtree of the roleBase node (maps to
-        `javax.naming.directory.SearchControls.SUBTREE_SCOPE`).
-
--   `authenticateUser` - boolean flag to disable authentication. Useful as an optimisation when this module is used just for
-    role mapping of a Subject's existing authenticated principals; default is `false`.
-
--   `referral` - specify how to handle referrals; valid values: `ignore`, `follow`, `throw`; default is `ignore`.
-
--   `debug` - boolean flag; if `true`, enable debugging; this is used only for testing or debugging; normally, it
-    should be set to `false`, or omitted; default is `false`
-
-Add user entries under the node specified by the `userBase` option. When creating a new user entry in the directory,
-choose an object class that supports the `userPassword` attribute (for example, the `person` or `inetOrgPerson` object
-classes are typically suitable). After creating the user entry, add the `userPassword` attribute, to hold the user's
-password.
-
-If you want to store role data in dedicated role entries (where each node represents a particular role), create a role
-entry as follows. Create a new child of the `roleBase` node, where the `objectClass` of the child is `groupOfNames`. Set
-the `cn` (or whatever attribute type is specified by `roleName`) of the new child node equal to the name of the
-role/group. Define a `member` attribute for each member of the role/group, setting the `member` value to the DN of the
-corresponding user (where the DN is specified either fully, `uid=jdoe,ou=User,ou=ActiveMQ,ou=system`, or partially,
-`uid=jdoe`).
-
-If you want to add roles to user entries, you would need to customize the directory schema, by adding a suitable
-attribute type to the user entry's object class. The chosen attribute type must be capable of handling multiple values.
+The LDAP login module enables you to perform authentication and authorization
+by checking the incoming credentials against user data stored in a central
+X.500 directory server. For systems that already have an X.500 directory server
+in place, this means that you can rapidly integrate ActiveMQ Artemis with the
+existing security database and user accounts can be managed using the X.500
+system. It is implemented by
+`org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule`.
+
+- `initialContextFactory` - must always be set to
+  `com.sun.jndi.ldap.LdapCtxFactory`
+
+- `connectionURL` - specify the location of the directory server using an ldap
+  URL, ldap://Host:Port. You can optionally qualify this URL, by adding a
+  forward slash, `/`, followed by the DN of a particular node in the directory
+  tree. For example, ldap://ldapserver:10389/ou=system.
+
+- `authentication` - specifies the authentication method used when binding to
+  the LDAP server. Can take either of the values, `simple` (username and
+  password), `GSSAPI` (Kerberos SASL) or `none` (anonymous).
+
+- `connectionUsername` - the DN of the user that opens the connection to the
+  directory server. For example, `uid=admin,ou=system`. Directory servers
+  generally require clients to present username/password credentials in order to
+  open a connection.
+
+- `connectionPassword` - the password that matches the DN from
+  `connectionUsername`. In the directory server, in the DIT, the password is
+  normally stored as a `userPassword` attribute in the corresponding directory
+  entry.
+
+- `saslLoginConfigScope` - the scope in JAAS configuration (login.config) to
+  use to obtain Kerberos initiator credentials when the `authentication` method
+  is SASL `GSSAPI`. The default value is `broker-sasl-gssapi`.
+
+- `connectionProtocol` - currently, the only supported value is a blank string.
+  In future, this option will allow you to select the Secure Socket Layer (SSL)
+  for the connection to the directory server. This option must be set explicitly
+  to an empty string, because it has no default value.
+
+- `userBase` - selects a particular subtree of the DIT to search for user
+  entries. The subtree is specified by a DN, which specifes the base node of
+  the subtree. For example, by setting this option to
+  `ou=User,ou=ActiveMQ,ou=system`, the search for user entries is restricted to
+  the subtree beneath the `ou=User,ou=ActiveMQ,ou=system` node.
+
+- `userSearchMatching` - specifies an LDAP search filter, which is applied to
+  the subtree selected by `userBase`.  Before passing to the LDAP search
+  operation, the string value you provide here is subjected to string
+  substitution, as implemented by the `java.text.MessageFormat` class.
+  Essentially, this means that the special string, `{0}`, is substituted by the
+  username, as extracted from the incoming client credentials.
+
+  After substitution, the string is interpreted as an LDAP search filter,
+  where the LDAP search filter syntax is defined by the IETF standard, RFC 2254.
+  A short introduction to the search filter syntax is available from Oracle's
+  JNDI tutorial, [Search
+  Filters](https://docs.oracle.com/javase/jndi/tutorial/basics/directory/filter.html).
+
+  For example, if this option is set to `(uid={0})` and the received username
+  is `jdoe`, the search filter becomes `(uid=jdoe)` after string substitution. If
+  the resulting search filter is applied to the subtree selected by the user
+  base, `ou=User,ou=ActiveMQ,ou=system`, it would match the entry,
+  `uid=jdoe,ou=User,ou=ActiveMQ,ou=system` (and possibly more deeply nested
+  entries, depending on the specified search depth—see the `userSearchSubtree`
+  option).
+
+- `userSearchSubtree` - specify the search depth for user entries, relative to
+  the node specified by `userBase`.  This option is a boolean. `false`
+  indicates it will try to match one of the child entries of the `userBase` node
+  (maps to `javax.naming.directory.SearchControls.ONELEVEL_SCOPE`). `true`
+    indicates it will try to match any entry belonging to the subtree of the
+  `userBase` node (maps to
+  `javax.naming.directory.SearchControls.SUBTREE_SCOPE`).
+
+- `userRoleName` - specifies the name of the multi-valued attribute of the user
+  entry that contains a list of role names for the user (where the role names
+  are interpreted as group names by the broker's authorization plug-in).  If you
+  omit this option, no role names are extracted from the user entry.
+
+- `roleBase` - if you want to store role data directly in the directory server,
+  you can use a combination of role options (`roleBase`, `roleSearchMatching`,
+  `roleSearchSubtree`, and `roleName`) as an alternative to (or in addition to)
+  specifying the `userRoleName` option. This option selects a particular subtree
+  of the DIT to search for role/group entries. The subtree is specified by a DN,
+  which specifes the base node of the subtree. For example, by setting this
+  option to `ou=Group,ou=ActiveMQ,ou=system`, the search for role/group entries
+  is restricted to the subtree beneath the `ou=Group,ou=ActiveMQ,ou=system` node.
+
+- `roleName` - specifies the attribute type of the role entry that contains the
+  name of the role/group (e.g. C, O, OU, etc.). If you omit this option the
+  full DN of the role is used.
+
+- `roleSearchMatching` - specifies an LDAP search filter, which is applied to
+  the subtree selected by `roleBase`.  This works in a similar manner to the
+  `userSearchMatching` option, except that it supports two substitution strings,
+  as follows:
+
+    - `{0}` - substitutes the full DN of the matched user entry (that is, the
+      result of the user search). For example, for the user, `jdoe`, the
+      substituted string could be `uid=jdoe,ou=User,ou=ActiveMQ,ou=system`.
+
+    - `{1}` - substitutes the received username. For example, `jdoe`.
+
+    For example, if this option is set to `(member=uid={1})` and the received
+    username is `jdoe`, the search filter becomes `(member=uid=jdoe)` after string
+    substitution (assuming ApacheDS search filter syntax). If the resulting search
+    filter is applied to the subtree selected by the role base,
+    `ou=Group,ou=ActiveMQ,ou=system`, it matches all role entries that have a
+    `member` attribute equal to `uid=jdoe` (the value of a `member` attribute is a
+    DN).
+
+    This option must always be set to enable role searching because it has no
+    default value. Leaving it unset disables role searching and the role
+    information must come from `userRoleName`.
+
+    If you use OpenLDAP, the syntax of the search filter is
+    `(member:=uid=jdoe)`.
+
+- `roleSearchSubtree` - specify the search depth for role entries, relative to
+  the node specified by `roleBase`.  This option can take boolean values, as
+  follows:
+
+    - `false` (default) - try to match one of the child entries of the roleBase
+      node (maps to `javax.naming.directory.SearchControls.ONELEVEL_SCOPE`).
+
+    - `true` — try to match any entry belonging to the subtree of the roleBase
+      node (maps to `javax.naming.directory.SearchControls.SUBTREE_SCOPE`).
+
+- `authenticateUser` - boolean flag to disable authentication. Useful as an
+  optimisation when this module is used just for role mapping of a Subject's
+  existing authenticated principals; default is `false`.
+
+- `referral` - specify how to handle referrals; valid values: `ignore`,
+  `follow`, `throw`; default is `ignore`.
+
+- `debug` - boolean flag; if `true`, enable debugging; this is used only for
+  testing or debugging; normally, it should be set to `false`, or omitted;
+  default is `false`
+
+Add user entries under the node specified by the `userBase` option. When
+creating a new user entry in the directory, choose an object class that
+supports the `userPassword` attribute (for example, the `person` or
+`inetOrgPerson` object classes are typically suitable). After creating the user
+entry, add the `userPassword` attribute, to hold the user's password.
+
+If you want to store role data in dedicated role entries (where each node
+represents a particular role), create a role entry as follows. Create a new
+child of the `roleBase` node, where the `objectClass` of the child is
+`groupOfNames`. Set the `cn` (or whatever attribute type is specified by
+`roleName`) of the new child node equal to the name of the role/group. Define a
+`member` attribute for each member of the role/group, setting the `member`
+value to the DN of the corresponding user (where the DN is specified either
+fully, `uid=jdoe,ou=User,ou=ActiveMQ,ou=system`, or partially, `uid=jdoe`).
+
+If you want to add roles to user entries, you would need to customize the
+directory schema, by adding a suitable attribute type to the user entry's
+object class. The chosen attribute type must be capable of handling multiple
+values.
 
 #### CertificateLoginModule
 
-The JAAS certificate authentication login module must be used in combination with SSL and the clients must be configured
-with their own certificate. In this scenario, authentication is actually performed during the SSL/TLS handshake, not
-directly by the JAAS certificate authentication plug-in. The role of the plug-in is as follows:
+The JAAS certificate authentication login module must be used in combination
+with SSL and the clients must be configured with their own certificate. In this
+scenario, authentication is actually performed during the SSL/TLS handshake,
+not directly by the JAAS certificate authentication plug-in. The role of the
+plug-in is as follows:
 
--   To further constrain the set of acceptable users, because only the user DNs explicitly listed in the relevant
-    properties file are eligible to be authenticated.
+- To further constrain the set of acceptable users, because only the user DNs
+  explicitly listed in the relevant properties file are eligible to be
+  authenticated.
 
--   To associate a list of groups with the received user identity, facilitating integration with the authorization feature.
+- To associate a list of groups with the received user identity, facilitating
+  integration with the authorization feature.
 
--   To require the presence of an incoming certificate (by default, the SSL/TLS layer is configured to treat the
-    presence of a client certificate as optional).
+- To require the presence of an incoming certificate (by default, the SSL/TLS
+  layer is configured to treat the presence of a client certificate as
+  optional).
 
-The JAAS certificate login module stores a collection of certificate DNs in a pair of flat files. The files associate a
-username and a list of group IDs with each DN.
+The JAAS certificate login module stores a collection of certificate DNs in a
+pair of flat files. The files associate a username and a list of group IDs with
+each DN.
 
 The certificate login module is implemented by the following class:
 
-    org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule
+```java
+org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule
+```
 
-The following `CertLogin` login entry shows how to configure certificate login module in the login.config file:
+The following `CertLogin` login entry shows how to configure certificate login
+module in the login.config file:
 
-    CertLogin {
-        org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule
-            debug=true
-            org.apache.activemq.jaas.textfiledn.user="users.properties"
-            org.apache.activemq.jaas.textfiledn.role="roles.properties";
-    };
+```
+CertLogin {
+    org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule
+        debug=true
+        org.apache.activemq.jaas.textfiledn.user="users.properties"
+        org.apache.activemq.jaas.textfiledn.role="roles.properties";
+};
+```
 
-In the preceding example, the JAAS realm is configured to use a single `org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule`
+In the preceding example, the JAAS realm is configured to use a single
+`org.apache.activemq.artemis.spi.core.security.jaas.TextFileCertificateLoginModule`
 login module. The options supported by this login module are as follows:
 
 -   `debug` - boolean flag; if true, enable debugging; this is used only for testing or debugging; normally,
@@ -632,116 +781,183 @@ compares it with the subject DNs in the `users.properties` file by testing for s
 be careful to ensure that the subject DNs appearing in the `users.properties` file are an exact match for the subject
 DNs extracted from the user certificates.
 
-Note: Technically, there is some residual ambiguity in the DN string format. For example, the `domainComponent` attribute
-could be represented in a string either as the string, `DC`, or as the OID, `0.9.2342.19200300.100.1.25`. Normally, you do
-not need to worry about this ambiguity. But it could potentially be a problem, if you changed the underlying
-implementation of the Java security layer.
-
-The easiest way to obtain the subject DNs from the user certificates is by invoking the `keytool` utility to print the
-certificate contents. To print the contents of a certificate in a keystore, perform the following steps:
+- `org.apache.activemq.jaas.textfiledn.user` - specifies the location of the
+  user properties file (relative to the directory containing the login
+  configuration file).
 
-1.   Export the certificate from the keystore file into a temporary file. For example, to export the certificate with
-     alias `broker-localhost` from the `broker.ks` keystore file, enter the following command:
+- `org.apache.activemq.jaas.textfiledn.role` - specifies the location of the
+  role properties file (relative to the directory containing the login
+  configuration file).
 
-        keytool -export -file broker.export -alias broker-localhost -keystore broker.ks -storepass password
+- `reload` - boolean flag; whether or not to reload the properties files when a
+  modification occurs; default is `false`
 
-     After running this command, the exported certificate is in the file, `broker.export`.
+In the context of the certificate login module, the `users.properties` file
+consists of a list of properties of the form, `UserName=StringifiedSubjectDN`.
+For example, to define the users, system, user, and guest, you could create a
+file like the following:
 
-1.   Print out the contents of the exported certificate. For example, to print out the contents of `broker.export`,
-     enter the following command:
-
-        keytool -printcert -file broker.export
-
-     Which should produce output similar to that shown here:
-
-        Owner: CN=localhost, OU=broker, O=Unknown, L=Unknown, ST=Unknown, C=Unknown
-        Issuer: CN=localhost, OU=broker, O=Unknown, L=Unknown, ST=Unknown, C=Unknown
-        Serial number: 4537c82e
-        Valid from: Thu Oct 19 19:47:10 BST 2006 until: Wed Jan 17 18:47:10 GMT 2007
-        Certificate fingerprints:
-                 MD5:  3F:6C:0C:89:A8:80:29:CC:F5:2D:DA:5C:D7:3F:AB:37
-                 SHA1: F0:79:0D:04:38:5A:46:CE:86:E1:8A:20:1F:7B:AB:3A:46:E4:34:5C
-
-     The string following `Owner:` gives the subject DN. The format used to enter the subject DN depends on your
-     platform. The `Owner:` string above could be represented as either `CN=localhost,\ OU=broker,\ O=Unknown,\ L=Unknown,\ ST=Unknown,\ C=Unknown`
-     or `CN=localhost,OU=broker,O=Unknown,L=Unknown,ST=Unknown,C=Unknown`.
-
-The `roles.properties` file consists of a list of properties of the form, `Role=UserList`, where `UserList` is a
-comma-separated list of users. For example, to define the roles `admins`, `users`, and `guests`, you could create a file
-like the following:
+```properties
+system=CN=system,O=Progress,C=US
+user=CN=humble user,O=Progress,C=US
+guest=CN=anon,O=Progress,C=DE
+```
 
-    admins=system
-    users=system,user
-    guests=guest
+Each username is mapped to a subject DN, encoded as a string (where the string
+encoding is specified by RFC 2253). For example, the system username is mapped
+to the `CN=system,O=Progress,C=US` subject DN. When performing authentication,
+the plug-in extracts the subject DN from the received certificate, converts it
+to the standard string format, and compares it with the subject DNs in the
+`users.properties` file by testing for string equality. Consequently, you must
+be careful to ensure that the subject DNs appearing in the `users.properties`
+file are an exact match for the subject DNs extracted from the user
+certificates.
+
+**Note:** Technically, there is some residual ambiguity in the DN string format.
+For example, the `domainComponent` attribute could be represented in a string
+either as the string, `DC`, or as the OID, `0.9.2342.19200300.100.1.25`.
+Normally, you do not need to worry about this ambiguity. But it could
+potentially be a problem, if you changed the underlying implementation of the
+Java security layer.
+
+The easiest way to obtain the subject DNs from the user certificates is by
+invoking the `keytool` utility to print the certificate contents. To print the
+contents of a certificate in a keystore, perform the following steps:
+
+1. Export the certificate from the keystore file into a temporary file. For
+   example, to export the certificate with alias `broker-localhost` from the
+`broker.ks` keystore file, enter the following command:
+
+   ```sh
+   keytool -export -file broker.export -alias broker-localhost -keystore broker.ks -storepass password
+   ```
+
+   After running this command, the exported certificate is in the file,
+  `broker.export`.
+
+1. Print out the contents of the exported certificate. For example, to print
+   out the contents of `broker.export`, enter the following command:
+
+   ```sh
+   keytool -printcert -file broker.export
+   ```
+
+   Which should produce output similar to that shown here:
+
+   ```
+   Owner: CN=localhost, OU=broker, O=Unknown, L=Unknown, ST=Unknown, C=Unknown
+   Issuer: CN=localhost, OU=broker, O=Unknown, L=Unknown, ST=Unknown, C=Unknown
+   Serial number: 4537c82e
+   Valid from: Thu Oct 19 19:47:10 BST 2006 until: Wed Jan 17 18:47:10 GMT 2007
+   Certificate fingerprints:
+            MD5:  3F:6C:0C:89:A8:80:29:CC:F5:2D:DA:5C:D7:3F:AB:37
+            SHA1: F0:79:0D:04:38:5A:46:CE:86:E1:8A:20:1F:7B:AB:3A:46:E4:34:5C
+   ```
+
+   The string following `Owner:` gives the subject DN. The format used to enter
+  the subject DN depends on your platform. The `Owner:` string above could be
+  represented as either `CN=localhost,\ OU=broker,\ O=Unknown,\ L=Unknown,\
+  ST=Unknown,\ C=Unknown` or
+  `CN=localhost,OU=broker,O=Unknown,L=Unknown,ST=Unknown,C=Unknown`.
+
+The `roles.properties` file consists of a list of properties of the form,
+`Role=UserList`, where `UserList` is a comma-separated list of users. For
+example, to define the roles `admins`, `users`, and `guests`, you could create
+a file like the following:
+
+```properties
+admins=system
+users=system,user
+guests=guest
+```
 
-The simplest way to make the login configuration available to JAAS is to add the directory containing the file,
-`login.config`, to your CLASSPATH.
+The simplest way to make the login configuration available to JAAS is to add
+the directory containing the file, `login.config`, to your CLASSPATH.
 
 ### Kerberos Authentication
 
-You must have the Kerberos infrastructure set up in your deployment environment before the server can accept Kerberos credentials.
-The server can acquire its Kerberos acceptor credentials by using JAAS and a Kerberos login module. The JDK provides the
+You must have the Kerberos infrastructure set up in your deployment environment
+before the server can accept Kerberos credentials.  The server can acquire its
+Kerberos acceptor credentials by using JAAS and a Kerberos login module. The
+JDK provides the
 [Krb5LoginModule](https://docs.oracle.com/javase/8/docs/jre/api/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.html)
-which executes the necessary Kerberos protocol steps to authenticate and obtain Kerberos credentials.
+which executes the necessary Kerberos protocol steps to authenticate and obtain
+Kerberos credentials.
 
 #### GSSAPI SASL Mechanism
 
-Using SASL over [AMQP](using-AMQP.md), Kerberos authentication is supported using the `GSSAPI` SASL mechanism.
-With SASL doing Kerberos authentication, TLS can be used to provide integrity and confidentially to the communications
+Using SASL over [AMQP](using-AMQP.md), Kerberos authentication is supported
+using the `GSSAPI` SASL mechanism.  With SASL doing Kerberos authentication,
+TLS can be used to provide integrity and confidentially to the communications
 channel in the normal way.
-The `GSSAPI` SASL mechanism must be enabled  on the AMQP acceptor in `broker.xml` by adding it to the `saslMechanisms` list url parameter:
+
+The `GSSAPI` SASL mechanism must be enabled  on the AMQP acceptor in
+`broker.xml` by adding it to the `saslMechanisms` list url parameter:
 `saslMechanisms="GSSAPI<,PLAIN, etc>`.
 
-    <acceptor name="amqp">tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI</acceptor>
+```xml
+<acceptor name="amqp">tcp://0.0.0.0:5672?protocols=AMQP;saslMechanisms=GSSAPI</acceptor>
+```
 
-The GSSAPI mechanism implementation on the server will use a JAAS configuration scope named `amqp-sasl-gssapi` to
-obtain it's Kerberos acceptor credentials. An alternative configuration scope can be specified on the AMQP acceptor
-using the url parameter: `saslLoginConfigScope=<some other scope>`.
+The GSSAPI mechanism implementation on the server will use a JAAS configuration
+scope named `amqp-sasl-gssapi` to obtain it's Kerberos acceptor credentials. An
+alternative configuration scope can be specified on the AMQP acceptor using the
+url parameter: `saslLoginConfigScope=<some other scope>`.
 
-An example configuration scope for `login.config` that will pick up a Kerberos keyTab for the Kerberos acceptor Principal
-`amqp/localhost` is as follows:
+An example configuration scope for `login.config` that will pick up a Kerberos
+keyTab for the Kerberos acceptor Principal `amqp/localhost` is as follows:
 
-    amqp-sasl-gssapi {
-        com.sun.security.auth.module.Krb5LoginModule required
-        isInitiator=false
-        storeKey=true
-        useKeyTab=true
-        principal="amqp/localhost"
-        debug=true;
-    };
+```
+amqp-sasl-gssapi {
+    com.sun.security.auth.module.Krb5LoginModule required
+    isInitiator=false
+    storeKey=true
+    useKeyTab=true
+    principal="amqp/localhost"
+    debug=true;
+};
+```
 
 #### Role Mapping
 
-On the server, the Kerberos authenticated Peer Principal can be added to the Subject's principal set as an Apache ActiveMQ Artemis UserPrincipal
-using the Apache ActiveMQ Artemis `Krb5LoginModule` login module. The [PropertiesLoginModule](#propertiesloginmodule) or
- [LDAPLoginModule](#ldaploginmodule) can then be used to map
-the authenticated Kerberos Peer Principal to an Apache ActiveMQ Artemis [Role](#role-based-security-for-addresses). Note
-that the Kerberos Peer Principal does not exist as an Apache ActiveMQ Artemis user, only as a role member.
- 
-    org.apache.activemq.artemis.spi.core.security.jaas.Krb5LoginModule required
-        ;
-    org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule optional
-        initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
-        connectionURL="ldap://localhost:1024"
-        authentication=GSSAPI
-        saslLoginConfigScope=broker-sasl-gssapi
-        connectionProtocol=s
-        userBase="ou=users,dc=example,dc=com"
-        userSearchMatching="(krb5PrincipalName={0})"
-        userSearchSubtree=true
-        authenticateUser=false
-        roleBase="ou=system"
-        roleName=cn
-        roleSearchMatching="(member={0})"
-        roleSearchSubtree=false
-        ;
+On the server, the Kerberos authenticated Peer Principal can be added to the
+Subject's principal set as an Apache ActiveMQ Artemis UserPrincipal using the
+Apache ActiveMQ Artemis `Krb5LoginModule` login module. The
+[PropertiesLoginModule](#propertiesloginmodule) or
+[LDAPLoginModule](#ldaploginmodule) can then be used to map the authenticated
+Kerberos Peer Principal to an Apache ActiveMQ Artemis
+[Role](#role-based-security-for-addresses). Note that the Kerberos Peer
+Principal does not exist as an Apache ActiveMQ Artemis user, only as a role
+member.
+
+```
+org.apache.activemq.artemis.spi.core.security.jaas.Krb5LoginModule required
+    ;
+org.apache.activemq.artemis.spi.core.security.jaas.LDAPLoginModule optional
+    initialContextFactory=com.sun.jndi.ldap.LdapCtxFactory
+    connectionURL="ldap://localhost:1024"
+    authentication=GSSAPI
+    saslLoginConfigScope=broker-sasl-gssapi
+    connectionProtocol=s
+    userBase="ou=users,dc=example,dc=com"
+    userSearchMatching="(krb5PrincipalName={0})"
+    userSearchSubtree=true
+    authenticateUser=false
+    roleBase="ou=system"
+    roleName=cn
+    roleSearchMatching="(member={0})"
+    roleSearchSubtree=false
+    ;
+```
 
 #### TLS Kerberos Cipher Suites
 
-The legacy [rfc2712](https://www.ietf.org/rfc/rfc2712.txt) defines TLS Kerberos cipher suites that can be used by TLS to negotiate
-Kerberos authentication. The cypher suites offered by rfc2712 are dated and insecure and rfc2712 has been superseded by
-SASL GSSAPI. However, for clients that don't support SASL (core client), using TLS can provide Kerberos authentication
-over an *unsecure* channel.
+The legacy [rfc2712](https://www.ietf.org/rfc/rfc2712.txt) defines TLS Kerberos
+cipher suites that can be used by TLS to negotiate Kerberos authentication. The
+cypher suites offered by rfc2712 are dated and insecure and rfc2712 has been
+superseded by SASL GSSAPI. However, for clients that don't support SASL (core
+client), using TLS can provide Kerberos authentication over an *unsecure*
+channel.
 
 
 ## SASL
@@ -751,81 +967,95 @@ Note: EXTERNAL will only be chosen if a subject is available from the TLS client
 
 ## Changing the username/password for clustering
 
-In order for cluster connections to work correctly, each node in the
-cluster must make connections to the other nodes. The username/password
-they use for this should always be changed from the installation default
-to prevent a security risk.
+In order for cluster connections to work correctly, each node in the cluster
+must make connections to the other nodes. The username/password they use for
+this should always be changed from the installation default to prevent a
+security risk.
 
 Please see [Management](management.md) for instructions on how to do this.
 
 
 ## Securing the console
 
-Artemis comes with a web console that allows user to browse Artemis documentation via an embedded server. By default the
-web access is plain HTTP. It is configured in `bootstrap.xml`:
+Artemis comes with a web console that allows user to browse Artemis
+documentation via an embedded server. By default the web access is plain HTTP.
+It is configured in `bootstrap.xml`:
 
-    <web bind="http://localhost:8161" path="web">
-        <app url="console" war="console.war"/>
-    </web>
+```xml
+<web bind="http://localhost:8161" path="web">
+    <app url="console" war="console.war"/>
+</web>
+```
 
-Alternatively you can edit the above configuration to enable secure access using HTTPS protocol. e.g.:
+Alternatively you can edit the above configuration to enable secure access
+using HTTPS protocol. e.g.:
 
-    <web bind="https://localhost:8443"
-        path="web"
-        keyStorePath="${artemis.instance}/etc/keystore.jks"
-        keyStorePassword="password">
-        <app url="jolokia" war="jolokia-war-1.3.5.war"/>
-    </web>
+```xml
+<web bind="https://localhost:8443"
+    path="web"
+    keyStorePath="${artemis.instance}/etc/keystore.jks"
+    keyStorePassword="password">
+    <app url="jolokia" war="jolokia-war-1.3.5.war"/>
+</web>
+```
 
-As shown in the example, to enable https the first thing to do is config the `bind` to be an `https` url. In addition,
-You will have to configure a few extra properties desribed as below.
+As shown in the example, to enable https the first thing to do is config the
+`bind` to be an `https` url. In addition, You will have to configure a few
+extra properties desribed as below.
 
--   `keyStorePath` - The path of the key store file.
+- `keyStorePath` - The path of the key store file.
 
--   `keyStorePassword` - The key store's password.
+- `keyStorePassword` - The key store's password.
 
--   `clientAuth` - The boolean flag indicates whether or not client authentication is required. Default is `false`.
+- `clientAuth` - The boolean flag indicates whether or not client
+  authentication is required. Default is `false`.
 
--   `trustStorePath` - The path of the trust store file. This is needed only if `clientAuth` is `true`.
+- `trustStorePath` - The path of the trust store file. This is needed only if
+  `clientAuth` is `true`.
 
--   `trustStorePassword` - The trust store's password.
+- `trustStorePassword` - The trust store's password.
 
 ## Controlling JMS ObjectMessage deserialization
 
-Artemis provides a simple class filtering mechanism with which a user can specify which
-packages are to be trusted and which are not. Objects whose classes are from trusted packages
-can be deserialized without problem, whereas those from 'not trusted' packages will be denied
-deserialization.
-
-Artemis keeps a `black list` to keep track of packages that are not trusted and a `white list`
-for trusted packages. By default both lists are empty, meaning any serializable object is
-allowed to be deserialized. If an object whose class matches one of the packages in black list,
-it is not allowed to be deserialized. If it matches one in the white list
-the object can be deserialized. If a package appears in both black list and white list,
-the one in black list takes precedence. If a class neither matches with `black list`
-nor with the `white list`, the class deserialization will be denied
-unless the white list is empty (meaning the user doesn't specify the white list at all).
+Artemis provides a simple class filtering mechanism with which a user can
+specify which packages are to be trusted and which are not. Objects whose
+classes are from trusted packages can be deserialized without problem, whereas
+those from 'not trusted' packages will be denied deserialization.
+
+Artemis keeps a `black list` to keep track of packages that are not trusted and
+a `white list` for trusted packages. By default both lists are empty, meaning
+any serializable object is allowed to be deserialized. If an object whose class
+matches one of the packages in black list, it is not allowed to be
+deserialized. If it matches one in the white list the object can be
+deserialized. If a package appears in both black list and white list, the one
+in black list takes precedence. If a class neither matches with `black list`
+nor with the `white list`, the class deserialization will be denied unless the
+white list is empty (meaning the user doesn't specify the white list at all).
 
 A class is considered as a 'match' if
 
--   its full name exactly matches one of the entries in the list.
--   its package matches one of the entries in the list or is a sub-package of one of the entries.
+- its full name exactly matches one of the entries in the list.
+- its package matches one of the entries in the list or is a sub-package of one
+  of the entries.
 
-For example, if a class full name is "org.apache.pkg1.Class1", some matching entries could be:
+

<TRUNCATED>

Mime
View raw message