http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/management.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/management.md b/docs/user-manual/en/management.md index 65b0b53..ca523b7 100644 --- a/docs/user-manual/en/management.md +++ b/docs/user-manual/en/management.md @@ -1,53 +1,56 @@ # Management -Apache ActiveMQ Artemis has an extensive *management API* that allows a user to modify a -server configuration, create new resources (e.g. addresses and queues), -inspect these resources (e.g. how many messages are currently held in a -queue) and interact with it (e.g. to remove messages from a queue). Apache ActiveMQ Artemis -also allows clients to subscribe to management notifications. +Apache ActiveMQ Artemis has an extensive *management API* that allows a user to +modify a server configuration, create new resources (e.g. addresses and +queues), inspect these resources (e.g. how many messages are currently held in +a queue) and interact with it (e.g. to remove messages from a queue). Apache +ActiveMQ Artemis also allows clients to subscribe to management notifications. There are four ways to access Apache ActiveMQ Artemis management API: -- Using JMX -- *JMX* is the standard way to manage Java applications +- Using JMX -- *JMX* is the standard way to manage Java applications -- Using Jolokia -- Jolokia exposes the JMX API of an application through a *REST interface* +- Using Jolokia -- Jolokia exposes the JMX API of an application through a + *REST interface* -- Using the Core Client -- management operations are sent to Apache ActiveMQ Artemis - server using *Core Client messages* +- Using the Core Client -- management operations are sent to Apache ActiveMQ + Artemis server using *Core Client messages* -- Using the Core JMS Client -- management operations are sent to Apache ActiveMQ Artemis - server using *Core JMS Client messages* +- Using any JMS Client -- management operations are sent to Apache ActiveMQ + Artemis server using *JMS Client messages* -Although there are four different ways to manage Apache ActiveMQ Artemis, each API supports -the same functionality. If it is possible to manage a resource using JMX -it is also possible to achieve the same result using Core messages. +Although there are four different ways to manage Apache ActiveMQ Artemis, each +API supports the same functionality. If it is possible to manage a resource +using JMX it is also possible to achieve the same result using Core messages. -Besides the programmatic management interfaces, a *Web Console* and a Command Line -*management utility* are also available to administrators of ActiveMQ Artemis. +Besides these four management interfaces, a [Web Console](management-console.md) +and a Command Line *management utility* are also available to administrators of +ActiveMQ Artemis. -The choice depends on your requirements, your application settings and -your environment to decide which way suits you best. +The choice depends on your requirements, your application settings, and your +environment to decide which way suits you best. -> **Note** +> **Note:** > -> In version 2 of Apache ActiveMQ Artemis the syntax used for MBean Object names has changed significantly due to changes -> in the addressing scheme. See the documentation for each individual resource for details on the new syntax. +> In version 2 of Apache ActiveMQ Artemis the syntax used for MBean Object +> names has changed significantly due to changes in the addressing scheme. See +> the documentation for each individual resource for details on the new syntax. ## The Management API -Regardless of the way you *invoke* management operations, the management -API is the same. +Regardless of the way you *invoke* management operations, the management API is +the same. -For each *managed resource*, there exists a Java interface describing -what operations can be invoked for this type of resource. +For each *managed resource*, there exists a Java interface describing what +operations can be invoked for this type of resource. -To learn about available *management operations*, see the Javadoc -for these interfaces. They are located in the +To learn about available *management operations*, see the Javadoc for these +interfaces. They are located in the `org.apache.activemq.artemis.api.core.management` package and they are named with the word `Control` at the end. -The way to invoke management operations depends on whether JMX, Core -messages, or Core JMS messages are used. +The way to invoke management operations depends on whether JMX, Core messages, +or JMS messages are used. ### Management API @@ -57,224 +60,219 @@ For full details of the API please consult the Javadoc. In summary: The `ActiveMQServerControl` interface is the entry point for broker management. -- Listing, creating, deploying and destroying queues +- Listing, creating, deploying and destroying queues - A list of deployed queues can be retrieved using the - `getQueueNames()` method. + A list of deployed queues can be retrieved using the `getQueueNames()` + method. - Queues can be created or destroyed using the management - operations `createQueue()` or `deployQueue()` or `destroyQueue()` + Queues can be created or destroyed using the management operations + `createQueue()` or `deployQueue()` or `destroyQueue()`. - `createQueue` will fail if the queue already exists while - `deployQueue` will do nothing. + `createQueue` will fail if the queue already exists while `deployQueue` will + do nothing. -- Listing and closing remote connections +- Listing and closing remote connections - Client's remote addresses can be retrieved using - `listRemoteAddresses()`. It is also possible to close the - connections associated with a remote address using the - `closeConnectionsForAddress()` method. + Client's remote addresses can be retrieved using `listRemoteAddresses()`. It + is also possible to close the connections associated with a remote address + using the `closeConnectionsForAddress()` method. - Alternatively, connection IDs can be listed using - `listConnectionIDs()` and all the sessions for a given connection ID - can be listed using `listSessions()`. + Alternatively, connection IDs can be listed using `listConnectionIDs()` and + all the sessions for a given connection ID can be listed using + `listSessions()`. -- Transaction heuristic operations +- Transaction heuristic operations - In case of a server crash, when the server restarts, it it possible - that some transaction requires manual intervention. The - `listPreparedTransactions()` method lists the transactions which are - in the prepared states (the transactions are represented as opaque - Base64 Strings.) To commit or rollback a given prepared transaction, - the `commitPreparedTransaction()` or `rollbackPreparedTransaction()` - method can be used to resolve heuristic transactions. Heuristically - completed transactions can be listed using the - `listHeuristicCommittedTransactions()` and - `listHeuristicRolledBackTransactions` methods. + In case of a server crash, when the server restarts, it it possible that some + transaction requires manual intervention. The `listPreparedTransactions()` + method lists the transactions which are in the prepared states (the + transactions are represented as opaque Base64 Strings.) To commit or rollback a + given prepared transaction, the `commitPreparedTransaction()` or + `rollbackPreparedTransaction()` method can be used to resolve heuristic + transactions. Heuristically completed transactions can be listed using the + `listHeuristicCommittedTransactions()` and + `listHeuristicRolledBackTransactions` methods. -- Enabling and resetting Message counters +- Enabling and resetting Message counters - Message counters can be enabled or disabled using the - `enableMessageCounters()` or `disableMessageCounters()` method. To - reset message counters, it is possible to invoke - `resetAllMessageCounters()` and `resetAllMessageCounterHistories()` - methods. + Message counters can be enabled or disabled using the + `enableMessageCounters()` or `disableMessageCounters()` method. To reset + message counters, it is possible to invoke `resetAllMessageCounters()` and + `resetAllMessageCounterHistories()` methods. -- Retrieving the server configuration and attributes +- Retrieving the server configuration and attributes - The `ActiveMQServerControl` exposes Apache ActiveMQ Artemis server configuration - through all its attributes (e.g. `getVersion()` method to retrieve - the server's version, etc.) + The `ActiveMQServerControl` exposes Apache ActiveMQ Artemis server + configuration through all its attributes (e.g. `getVersion()` method to + retrieve the server's version, etc.) -- Listing, creating and destroying Core bridges and diverts +- Listing, creating and destroying Core bridges and diverts - A list of deployed core bridges (resp. diverts) can be retrieved - using the `getBridgeNames()` (resp. `getDivertNames()`) method. + A list of deployed core bridges (resp. diverts) can be retrieved using the + `getBridgeNames()` (resp. `getDivertNames()`) method. - Core bridges (resp. diverts) can be created or destroyed using the - management operations `createBridge()` and `destroyBridge()` (resp. - `createDivert()` and `destroyDivert()`). + Core bridges (resp. diverts) can be created or destroyed using the management + operations `createBridge()` and `destroyBridge()` (resp. `createDivert()` and + `destroyDivert()`). -- It is possible to stop the server and force failover to occur with - any currently attached clients. +- It is possible to stop the server and force failover to occur with any + currently attached clients. - To do this use the `forceFailover()` operation. + To do this use the `forceFailover()` operation. - > **Note** - > - > Since this method actually stops the server you will probably - > receive some sort of error depending on which management service - > you use to call it. + > **Note:** + > + > Since this method actually stops the server you will probably receive some + > sort of error depending on which management service you use to call it. #### Address Management Individual addresses can be managed using the `AddressControl` interface. -- Modifying roles and permissions for an address +- Modifying roles and permissions for an address - You can add or remove roles associated to a queue using the - `addRole()` or `removeRole()` methods. You can list all the roles - associated to the queue with the `getRoles()` method + You can add or remove roles associated to a queue using the `addRole()` or + `removeRole()` methods. You can list all the roles associated to the queue with + the `getRoles()` method #### Queue Management -The bulk of the management API deals with queues. The -`QueueControl` interface defines the queue management operations. +The bulk of the management API deals with queues. The `QueueControl` interface +defines the queue management operations. -Most of the management operations on queues take either a single message -ID (e.g. to remove a single message) or a filter (e.g. to expire all -messages with a given property.) +Most of the management operations on queues take either a single message ID +(e.g. to remove a single message) or a filter (e.g. to expire all messages with +a given property.) -> **Note** +> **Note:** > -> Passing `null` or an empty string in the `filter` parameter means that -> the management operation will be performed on *all messages* in a queue. +> Passing `null` or an empty string in the `filter` parameter means that the +> management operation will be performed on *all messages* in a queue. -- Expiring, sending to a dead letter address and moving messages +- Expiring, sending to a dead letter address and moving messages - Messages can be expired from a queue by using the `expireMessages()` - method. If an expiry address is defined, messages will be sent to - it, otherwise they are discarded. The queue's expiry address can be - set with the `setExpiryAddress()` method. + Messages can be expired from a queue by using the `expireMessages()` method. + If an expiry address is defined, messages will be sent to it, otherwise they + are discarded. The queue's expiry address can be set with the + `setExpiryAddress()` method. - Messages can also be sent to a dead letter address with the - `sendMessagesToDeadLetterAddress()` method. It returns the number of - messages which are sent to the dead letter address. If a dead letter - address is not defined, message are removed from the queue and - discarded. The queue's dead letter address can be set with the - `setDeadLetterAddress()` method. + Messages can also be sent to a dead letter address with the + `sendMessagesToDeadLetterAddress()` method. It returns the number of messages + which are sent to the dead letter address. If a dead letter address is not + defined, message are removed from the queue and discarded. The queue's dead + letter address can be set with the `setDeadLetterAddress()` method. - Messages can also be moved from a queue to another queue by using - the `moveMessages()` method. + Messages can also be moved from a queue to another queue by using the + `moveMessages()` method. -- Listing and removing messages +- Listing and removing messages - Messages can be listed from a queue by using the `listMessages()` - method which returns an array of `Map`, one `Map` for each message. + Messages can be listed from a queue by using the `listMessages()` method + which returns an array of `Map`, one `Map` for each message. - Messages can also be removed from the queue by using the - `removeMessages()` method which returns a `boolean` for the single - message ID variant or the number of removed messages for the filter - variant. The `removeMessages()` method takes a `filter` argument to - remove only filtered messages. Setting the filter to an empty string - will in effect remove all messages. + Messages can also be removed from the queue by using the `removeMessages()` + method which returns a `boolean` for the single message ID variant or the + number of removed messages for the filter variant. The `removeMessages()` + method takes a `filter` argument to remove only filtered messages. Setting the + filter to an empty string will in effect remove all messages. -- Counting messages +- Counting messages - The number of messages in a queue is returned by the - `getMessageCount()` method. Alternatively, the `countMessages()` - will return the number of messages in the queue which *match a given - filter*. + The number of messages in a queue is returned by the `getMessageCount()` + method. Alternatively, the `countMessages()` will return the number of messages + in the queue which *match a given filter*. -- Changing message priority +- Changing message priority - The message priority can be changed by using the - `changeMessagesPriority()` method which returns a `boolean` for the - single message ID variant or the number of updated messages for the - filter variant. + The message priority can be changed by using the `changeMessagesPriority()` + method which returns a `boolean` for the single message ID variant or the + number of updated messages for the filter variant. -- Message counters +- Message counters - Message counters can be listed for a queue with the - `listMessageCounter()` and `listMessageCounterHistory()` methods - (see Message Counters section). The message counters can also be - reset for a single queue using the `resetMessageCounter()` method. + Message counters can be listed for a queue with the `listMessageCounter()` + and `listMessageCounterHistory()` methods (see Message Counters section). The + message counters can also be reset for a single queue using the + `resetMessageCounter()` method. -- Retrieving the queue attributes +- Retrieving the queue attributes - The `QueueControl` exposes queue settings through its - attributes (e.g. `getFilter()` to retrieve the queue's filter if it - was created with one, `isDurable()` to know whether the queue is - durable or not, etc.) + The `QueueControl` exposes queue settings through its attributes (e.g. + `getFilter()` to retrieve the queue's filter if it was created with one, + `isDurable()` to know whether the queue is durable or not, etc.) -- Pausing and resuming Queues +- Pausing and resuming Queues - The `QueueControl` can pause and resume the underlying queue. When a - queue is paused, it will receive messages but will not deliver them. - When it's resumed, it'll begin delivering the queued messages, if - any. + The `QueueControl` can pause and resume the underlying queue. When a queue is + paused, it will receive messages but will not deliver them. When it's resumed, + it'll begin delivering the queued messages, if any. #### Other Resources Management -Apache ActiveMQ Artemis allows to start and stop its remote resources (acceptors, -diverts, bridges, etc.) so that a server can be taken off line for a -given period of time without stopping it completely (e.g. if other -management operations must be performed such as resolving heuristic -transactions). These resources are: +Apache ActiveMQ Artemis allows to start and stop its remote resources +(acceptors, diverts, bridges, etc.) so that a server can be taken off line for +a given period of time without stopping it completely (e.g. if other management +operations must be performed such as resolving heuristic transactions). These +resources are: -- Acceptors +- Acceptors - They can be started or stopped using the `start()` or. `stop()` - method on the `AcceptorControl` interface. The acceptors parameters - can be retrieved using the `AcceptorControl` attributes (see [Understanding Acceptors](configuring-transports.md)) + They can be started or stopped using the `start()` or. `stop()` method on the + `AcceptorControl` interface. The acceptors parameters can be retrieved using + the `AcceptorControl` attributes (see [Understanding + Acceptors](configuring-transports.md)) -- Diverts +- Diverts - They can be started or stopped using the `start()` or `stop()` - method on the `DivertControl` interface. Diverts - parameters can be retrieved using the `DivertControl` attributes - (see [Diverting and Splitting Message Flows)](diverts.md)) + They can be started or stopped using the `start()` or `stop()` method on the + `DivertControl` interface. Diverts parameters can be retrieved using the + `DivertControl` attributes (see [Diverting and Splitting Message + Flows)](diverts.md)) -- Bridges +- Bridges - They can be started or stopped using the `start()` (resp. `stop()`) - method on the `BridgeControl` interface. Bridges parameters can be retrieved - using the `BridgeControl` attributes (see [Core bridges](core-bridges.md)) + They can be started or stopped using the `start()` (resp. `stop()`) method on + the `BridgeControl` interface. Bridges parameters can be retrieved using the + `BridgeControl` attributes (see [Core bridges](core-bridges.md)) -- Broadcast groups +- Broadcast groups - They can be started or stopped using the `start()` or `stop()` - method on the `BroadcastGroupControl` interface. Broadcast groups - parameters can be retrieved using the `BroadcastGroupControl` - attributes (see [Clusters](clusters.md)) + They can be started or stopped using the `start()` or `stop()` method on the + `BroadcastGroupControl` interface. Broadcast groups parameters can be retrieved + using the `BroadcastGroupControl` attributes (see [Clusters](clusters.md)) -- Cluster connections +- Cluster connections - They can be started or stopped using the `start()` or `stop()` - method on the `ClusterConnectionControl` interface. Cluster - connections parameters can be retrieved using the - `ClusterConnectionControl` attributes (see [Clusters](clusters.md)) + They can be started or stopped using the `start()` or `stop()` method on the + `ClusterConnectionControl` interface. Cluster connections parameters can be + retrieved using the `ClusterConnectionControl` attributes (see + [Clusters](clusters.md)) ## Using Management Via JMX Apache ActiveMQ Artemis can be managed using [JMX](http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html). -The management API is exposed by Apache ActiveMQ Artemis using MBeans interfaces. -Apache ActiveMQ Artemis registers its resources with the domain `org.apache.activemq.artemis`. +The management API is exposed by Apache ActiveMQ Artemis using MBeans +interfaces. Apache ActiveMQ Artemis registers its resources with the domain +`org.apache.activemq.artemis`. -For example, the `ObjectName` to manage the anycast queue `exampleQueue` on the address `exampleAddress` is: +For example, the `ObjectName` to manage the anycast queue `exampleQueue` on the +address `exampleAddress` is: - org.apache.activemq.artemis:broker=<brokerName>,component=addresses,address="exampleAddress",subcomponent=queues,routing-type="anycast",queue="exampleQueue" +``` +org.apache.activemq.artemis:broker=<brokerName>,component=addresses,address="exampleAddress",subcomponent=queues,routing-type="anycast",queue="exampleQueue" +``` and the MBean is: - org.apache.activemq.artemis.api.core.management.QueueControl +``` +org.apache.activemq.artemis.api.core.management.QueueControl +``` The MBean `ObjectName`'s are built using the helper class `org.apache.activemq.artemis.api.core.management.ObjectNameBuilder`. You can -also use `jconsole` to find the `ObjectName` of the MBean you want to -manage. +also use `jconsole` to find the `ObjectName` of the MBean you want to manage. Example usage of the `ObjectNameBuilder` to obtain `ActiveMQServerControl`'s name: @@ -284,39 +282,43 @@ objectNameBuilder = ObjectNameBuilder.create(ArtemisResolver.DEFAULT_DOMAIN, bro serverObjectName = objectNameBuilder.getActiveMQServerObjectName() ``` -Managing Apache ActiveMQ Artemis using JMX is identical to management of any Java -Applications using JMX. It can be done by reflection or by creating +Managing Apache ActiveMQ Artemis using JMX is identical to management of any +Java Applications using JMX. It can be done by reflection or by creating proxies of the MBeans. ### Configuring JMX -By default, JMX is enabled to manage Apache ActiveMQ Artemis. It can be disabled by -setting `jmx-management-enabled` to `false` in -`broker.xml`: +By default, JMX is enabled to manage Apache ActiveMQ Artemis. It can be +disabled by setting `jmx-management-enabled` to `false` in `broker.xml`: - <!-- false to disable JMX management for Apache ActiveMQ Artemis --> - <jmx-management-enabled>false</jmx-management-enabled> - +```xml +<!-- false to disable JMX management for Apache ActiveMQ Artemis --> +<jmx-management-enabled>false</jmx-management-enabled> +``` + #### Role Based Authorisation for JMX -Although by default Artemis uses the Java Virtual Machine's `Platform MBeanServer` -this is guarded using role based authentication that leverages Artemis's JAAS plugin support. -This is configured via the `authorisation` element in the `management.xml` configuration file -and can be used to restrict access to attributes and methods on mbeans. +Although by default Artemis uses the Java Virtual Machine's `Platform +MBeanServer` this is guarded using role based authentication that leverages +Artemis's JAAS plugin support. This is configured via the `authorisation` +element in the `management.xml` configuration file and can be used to restrict +access to attributes and methods on mbeans. -There are 3 elements within the `authorisation` element, `whitelist`, `default-access` and -`role-access`, Lets discuss each in turn. +There are 3 elements within the `authorisation` element, `whitelist`, +`default-access` and `role-access`, Lets discuss each in turn. -Whitelist contains a list of mBeans that will by pass the authentication, this is typically -used for any mbeans that are needed by the console to run etc. The default configuration is: +Whitelist contains a list of mBeans that will by pass the authentication, this +is typically used for any mbeans that are needed by the console to run etc. The +default configuration is: ```xml <whitelist> <entry domain="hawtio"/> </whitelist> ``` -This means that any mbean with the domain `hawtio` will be allowed access without authorisation. for instance -`hawtio:plugin=artemis`. You can also use wildcards for the mBean properties so the following would also match. +This means that any mbean with the domain `hawtio` will be allowed access +without authorisation. for instance `hawtio:plugin=artemis`. You can also use +wildcards for the mBean properties so the following would also match. ```xml <whitelist> @@ -324,32 +326,35 @@ This means that any mbean with the domain `hawtio` will be allowed access withou </whitelist> ``` -The `role-access`defines how roles are mapped to particular mBeans and its attributes and methods, -the default configuration looks like: +The `role-access`defines how roles are mapped to particular mBeans and its +attributes and methods, the default configuration looks like: ```xml <role-access> - <match domain="org.apache.activemq.artemis"> - <access method="list*" roles="view,update,amq"/> - <access method="get*" roles="view,update,amq"/> - <access method="is*" roles="view,update,amq"/> - <access method="set*" roles="update,amq"/> - <access method="*" roles="amq"/> - </match> + <match domain="org.apache.activemq.artemis"> + <access method="list*" roles="view,update,amq"/> + <access method="get*" roles="view,update,amq"/> + <access method="is*" roles="view,update,amq"/> + <access method="set*" roles="update,amq"/> + <access method="*" roles="amq"/> + </match> </role-access> ``` -This contains 1 match and will be applied to any mBean that has the domain `org.apache.activemq.artemis`. -Any access to any mBeans that have this domain are controlled by the `access` elements which contain a -method and a set of roles. The method being invoked will be used to pick the closest matching method and -the roles for this will be applied for access. For instance if you try the invoke a method called `listMessages` on an mBean -with the `org.apache.activemq.artemis` domain then this would match the `access` with the method of `list*`. -You could also explicitly configure this by using the full method name, like so: +This contains 1 match and will be applied to any mBean that has the domain +`org.apache.activemq.artemis`. Any access to any mBeans that have this domain +are controlled by the `access` elements which contain a method and a set of +roles. The method being invoked will be used to pick the closest matching +method and the roles for this will be applied for access. For instance if you +try the invoke a method called `listMessages` on an mBean with the +`org.apache.activemq.artemis` domain then this would match the `access` with +the method of `list*`. You could also explicitly configure this by using the +full method name, like so: ```xml <access method="listMessages" roles="view,update,amq"/> ``` -You can also match specific mBeans within a domain by adding a key attribute that is used to match one of the properties -on the mBean, like: +You can also match specific mBeans within a domain by adding a key attribute +that is used to match one of the properties on the mBean, like: ```xml <match domain="org.apache.activemq.artemis" key="subcomponent=queues"> @@ -360,9 +365,11 @@ on the mBean, like: <access method="*" roles="amq"/> </match> ``` -You could also match a specific queue for instance : +You could also match a specific queue for instance: -`org.apache.activemq.artemis:broker=<brokerName>,component=addresses,address="exampleAddress",subcomponent=queues,routing-type="anycast",queue="exampleQueue"` +``` +org.apache.activemq.artemis:broker=<brokerName>,component=addresses,address="exampleAddress",subcomponent=queues,routing-type="anycast",queue="exampleQueue" +``` by configuring: @@ -376,85 +383,111 @@ by configuring: </match> ``` -Access to JMX mBean attributes are converted to method calls so these are controlled via the `set*`, `get*` and `is*`. -The `*` access is the catch all for everything other method that isn't specifically matched. +Access to JMX mBean attributes are converted to method calls so these are +controlled via the `set*`, `get*` and `is*`. The `*` access is the catch all +for everything other method that isn't specifically matched. -The `default-access` element is basically the catch all for every method call that isn't handled via the `role-access` configuration. -This has teh same semantics as a `match` element. +The `default-access` element is basically the catch all for every method call +that isn't handled via the `role-access` configuration. This has teh same +semantics as a `match` element. -> **Note** +> **Note:** > -> If JMX is enabled, Apache ActiveMQ Artemis can *not* be managed locally using `jconsole` when connecting as a local process, -> this is because jconsole does not using any authentication when connecting this way. If you want to use jconsole you will -either have to disable authentication, by removing the `authentication` element or enable remote access. +> If JMX is enabled, Apache ActiveMQ Artemis can *not* be managed locally using +> `jconsole` when connecting as a local process, this is because jconsole does +> not using any authentication when connecting this way. If you want to use +> jconsole you will either have to disable authentication, by removing the +> `authentication` element or enable remote access. #### Configuring remote JMX Access By default remote JMX access to Artemis is disabled for security reasons. -Artemis has a JMX agent which allows access to JMX mBeans remotely. This is configured via the `connector` element in the -`management.xml` configuration file. To enable this you simply add the following xml: +Artemis has a JMX agent which allows access to JMX mBeans remotely. This is +configured via the `connector` element in the `management.xml` configuration +file. To enable this you simply add the following xml: ```xml <connector connector-port="1099"/> ``` -This exposes the agent remotely on the port 1099. If you were connecting via jconsole you would connect as a remote process -using the service url `service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi` and an appropriate user name and password. +This exposes the agent remotely on the port 1099. If you were connecting via +jconsole you would connect as a remote process using the service url +`service:jmx:rmi:///jndi/rmi://localhost:1099/jmxrmi` and an appropriate user +name and password. You can also configure the connector using the following: -- connector-host +- `connector-host` - The host to expose the agent on -- connector-port + The host to expose the agent on. + +- `connector-port` - The port to expose the agent on -- jmx-realm + The port to expose the agent on. - The jmx realm to use for authentication, defaults to `activemq` to match the JAAS configuration. -- object-name +- `jmx-realm` - The object name to expose the remote connector on, default is `connector:name=rmi` -- secured + The jmx realm to use for authentication, defaults to `activemq` to match the + JAAS configuration. + +- `object-name` - Whether the connector is secured using SSL -- key-store-path + The object name to expose the remote connector on; default is + `connector:name=rmi`. + +- `secured` - The location of the keystore -- key-store-password + Whether the connector is secured using SSL. + +- `key-store-path` - The keystore password -- key-store-provider - The provider, JKS by default -- trust-store-path + The location of the keystore. - The location of the truststore -- trust-store-password +- `key-store-password` - The trustore password -- trust-store-provider + The keystore password. - The provider, JKS by default +- `key-store-provider` -> **Note** + The provider; `JKS` by default. + +- `trust-store-path` + + The location of the truststore. + +- `trust-store-password` + + The trustore password. + +- `trust-store-provider` + + The provider; `JKS` by default. + +> **Note:** > -> It is important to note that the rmi registry will pick an ip address to bind to, If you have a multi IP addresses/NICs -> present on the system then you can choose the ip address to use by adding the following to artemis.profile +> It is important to note that the rmi registry will pick an ip address to bind +> to, If you have a multi IP addresses/NICs present on the system then you can +> choose the ip address to use by adding the following to artemis.profile > `-Djava.rmi.server.hostname=localhost` -> **Note** +> **Note:** > -> Remote connections using the default JVM Agent not enabled by default as Artemis exposes the mBean Server via its own configuration. -> This is so Artemis can leverage the JAAS authentication layer via JMX. If you want to expose this then you will need to -> disable both the connector and the authorisation by removing them from the `management.xml` configuration. -> Please refer to [Java Management guide](https://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html) -> to configure the server for remote management (system properties must be set in `artemis.profile`). - -By default, Apache ActiveMQ Artemis server uses the JMX domain "org.apache.activemq.artemis". -To manage several Apache ActiveMQ Artemis servers from the *same* MBeanServer, the JMX -domain can be configured for each individual Apache ActiveMQ Artemis server by setting -`jmx-domain` in `broker.xml`: +> Remote connections using the default JVM Agent not enabled by default as +> Artemis exposes the mBean Server via its own configuration. This is so +> Artemis can leverage the JAAS authentication layer via JMX. If you want to +> expose this then you will need to disable both the connector and the +> authorisation by removing them from the `management.xml` configuration. +> Please refer to [Java Management +> guide](https://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html) +> to configure the server for remote management (system properties must be set +> in `artemis.profile`). + +By default, Apache ActiveMQ Artemis server uses the JMX domain +"org.apache.activemq.artemis". To manage several Apache ActiveMQ Artemis +servers from the *same* MBeanServer, the JMX domain can be configured for each +individual Apache ActiveMQ Artemis server by setting `jmx-domain` in +`broker.xml`: ```xml <!-- use a specific JMX domain for ActiveMQ Artemis MBeans --> @@ -463,81 +496,87 @@ domain can be configured for each individual Apache ActiveMQ Artemis server by s ### Example -See the [Examples](examples.md) chapter for an example which shows how to use a remote connection to JMX -and MBean proxies to manage Apache ActiveMQ Artemis. +See the [JMX Management Example](examples.md#jmx-management) which shows how to +use a remote connection to JMX and MBean proxies to manage Apache ActiveMQ +Artemis. ### Exposing JMX using Jolokia The default Broker configuration ships with the [Jolokia](https://jolokia.org) -HTTP agent deployed as a Web Application. Jolokia is a remote -JMX-over-HTTP bridge that exposes MBeans. For a full guide as -to how to use it refer to [Jolokia Documentation](https://jolokia.org/documentation.html), -however a simple example to query the broker's version would -be to use a browser and go to the URL [http://username:password@localhost:8161/console/jolokia/read/org.apache.activemq.artemis:broker="0.0.0.0"/Version](). +HTTP agent deployed as a web application. Jolokia is a remote JMX-over-HTTP +bridge that exposes MBeans. For a full guide as to how to use it refer to +[Jolokia Documentation](https://jolokia.org/documentation.html), however a +simple example to query the broker's version would be to use a browser and go +to the URL +[http://username:password@localhost:8161/console/jolokia/read/org.apache.activemq.artemis:broker="0.0.0.0"/Version](). This would give you back something like the following: - {"request":{"mbean":"org.apache.activemq.artemis:broker=\"0.0.0.0\"","attribute":"Version","type":"read"},"value":"2.0.0-SNAPSHOT","timestamp":1487017918,"status":200} +``` +{"request":{"mbean":"org.apache.activemq.artemis:broker=\"0.0.0.0\"","attribute":"Version","type":"read"},"value":"2.0.0-SNAPSHOT","timestamp":1487017918,"status":200} +``` ### JMX and the Console -The console that ships with Artemis uses Jolokia under the covers which in turn uses JMX. This will use the authentication -configuration in the `management.xml` file as described in the previous section. This means that when mBeans are accessed -via the console the credentials used to log into the console and the roles associated with them. By default access to the -console is only allow via users with the amq role. This is configured in the `artemis.profile` via the system property `-Dhawtio.role=amq`. -You can configure multiple roles by changing this to `-Dhawtio.roles=amq,view,update`. +The console that ships with Artemis uses Jolokia under the covers which in turn +uses JMX. This will use the authentication configuration in the +`management.xml` file as described in the previous section. This means that +when mBeans are accessed via the console the credentials used to log into the +console and the roles associated with them. By default access to the console is +only allow via users with the amq role. This is configured in the +`artemis.profile` via the system property `-Dhawtio.role=amq`. You can +configure multiple roles by changing this to `-Dhawtio.roles=amq,view,update`. -If a user doesn't have the correct role to invoke a specific operation then this will display an authorisation exception -in the console. +If a user doesn't have the correct role to invoke a specific operation then +this will display an authorisation exception in the console. ## Using Management Message API -The management message API in ActiveMQ Artemis is accessed by sending Core Client messages -to a special address, the *management address*. +The management message API in ActiveMQ Artemis is accessed by sending Core +Client messages to a special address, the *management address*. *Management messages* are regular Core Client messages with well-known -properties that the server needs to understand to interact with the -management API: +properties that the server needs to understand to interact with the management +API: -- The name of the managed resource +- The name of the managed resource -- The name of the management operation +- The name of the management operation -- The parameters of the management operation +- The parameters of the management operation -When such a management message is sent to the management address, -Apache ActiveMQ Artemis server will handle it, extract the information, invoke the +When such a management message is sent to the management address, Apache +ActiveMQ Artemis server will handle it, extract the information, invoke the operation on the managed resources and send a *management reply* to the management message's reply-to address (specified by `ClientMessageImpl.REPLYTO_HEADER_NAME`). -A `ClientConsumer` can be used to consume the management reply and -retrieve the result of the operation (if any) stored in the reply's -body. For portability, results are returned as a [JSON](https://json.org) -String rather than Java Serialization (the +A `ClientConsumer` can be used to consume the management reply and retrieve the +result of the operation (if any) stored in the reply's body. For portability, +results are returned as a [JSON](https://json.org) String rather than Java +Serialization (the `org.apache.activemq.artemis.api.core.management.ManagementHelper` can be used to convert the JSON string to Java objects). -These steps can be simplified to make it easier to invoke management -operations using Core messages: +These steps can be simplified to make it easier to invoke management operations +using Core messages: -1. Create a `ClientRequestor` to send messages to the management - address and receive replies +1. Create a `ClientRequestor` to send messages to the management address and + receive replies -2. Create a `ClientMessage` +2. Create a `ClientMessage` -3. Use the helper class - `org.apache.activemq.artemis.api.core.management.ManagementHelper` to fill - the message with the management properties +3. Use the helper class + `org.apache.activemq.artemis.api.core.management.ManagementHelper` to fill + the message with the management properties -4. Send the message using the `ClientRequestor` +4. Send the message using the `ClientRequestor` -5. Use the helper class - `org.apache.activemq.artemis.api.core.management.ManagementHelper` to - retrieve the operation result from the management reply +5. Use the helper class + `org.apache.activemq.artemis.api.core.management.ManagementHelper` to + retrieve the operation result from the management reply. -For example, to find out the number of messages in the queue -`exampleQueue`: +For example, to find out the number of messages in the queue `exampleQueue`: ```java ClientSession session = ... @@ -550,35 +589,38 @@ int count = (Integer) ManagementHelper.getResult(reply); System.out.println("There are " + count + " messages in exampleQueue"); ``` -Management operation name and parameters must conform to the Java -interfaces defined in the `management` packages. +Management operation name and parameters must conform to the Java interfaces +defined in the `management` packages. Names of the resources are built using the helper class `org.apache.activemq.artemis.api.core.management.ResourceNames` and are straightforward (e.g. `queue.exampleQueue` for `QueueControl` of the Queue `exampleQueue`, or `broker` for the `ActiveMQServerControl`). -> *NOTE* +> **Note:** > -> The `ManagementHelper` class can be used only with Core JMS messages. -> When called with a message from a different JMS library, an exception will be thrown. +> The `ManagementHelper` class can be used only with Core JMS messages. When +> called with a message from a different JMS library, an exception will be +> thrown. ### Configuring Management The management address to send management messages is configured in `broker.xml`: - <management-address>activemq.management</management-address> +```xml +<management-address>activemq.management</management-address> +``` By default, the address is `activemq.management`. -The management address requires a *special* user permission `manage` to -be able to receive and handle management messages. This is also -configured in broker.xml: +The management address requires a *special* user permission `manage` to be able +to receive and handle management messages. This is also configured in +broker.xml: ```xml <!-- users with the admin role will be allowed to manage --> -<!-- Apache ActiveMQ Artemis using management messages --> +<!-- Apache ActiveMQ Artemis using management messages --> <security-setting match="activemq.management"> <permission type="manage" roles="admin" /> </security-setting> @@ -586,49 +628,50 @@ configured in broker.xml: ### Example -See the [Examples](examples.md) chapter for an example which shows -how to use JMS messages to manage the Apache ActiveMQ Artemis server. +See the [Management Example](examples.md#management) which shows how to use JMS +messages to manage the Apache ActiveMQ Artemis server. ## Management Notifications -Apache ActiveMQ Artemis emits *notifications* to inform listeners of potentially -interesting events (creation of new resources, security violation, +Apache ActiveMQ Artemis emits *notifications* to inform listeners of +potentially interesting events (creation of new resources, security violation, etc.). These notifications can be received by two different ways: -- JMX notifications +- JMX notifications -- Notification messages +- Notification messages ### JMX Notifications -If JMX is enabled (see Configuring JMX section), JMX notifications can be received by -subscribing to `org.apache.activemq.artemis:type=Broker,brokerName=<broker name>,module=Core,serviceType=Server` for -notifications on resources. +If JMX is enabled (see Configuring JMX section), JMX notifications can be +received by subscribing to +`org.apache.activemq.artemis:type=Broker,brokerName=<broker +name>,module=Core,serviceType=Server` for notifications on resources. ### Notification Messages -Apache ActiveMQ Artemis defines a special *management notification address*. -Queues can be bound to this address so that clients will receive -management notifications as messages. +Apache ActiveMQ Artemis defines a special *management notification address*. +Queues can be bound to this address so that clients will receive management +notifications as messages. -A client which wants to receive management notifications must -create a queue bound to the management notification address. It can -then receive the notifications from its queue. +A client which wants to receive management notifications must create a queue +bound to the management notification address. It can then receive the +notifications from its queue. -Notifications messages are regular messages with additional -properties corresponding to the notification (its type, when it -occurred, the resources which were concerned, etc.). +Notifications messages are regular messages with additional properties +corresponding to the notification (its type, when it occurred, the resources +which were concerned, etc.). -Since notifications are regular messages, it is possible to use -message selectors to filter out notifications and receives only a subset -of all the notifications emitted by the server. +Since notifications are regular messages, it is possible to use message +selectors to filter out notifications and receives only a subset of all the +notifications emitted by the server. #### Configuring The Management Notification Address -The management notification address to receive management notifications -is configured in `broker.xml`: +The management notification address to receive management notifications is +configured in `broker.xml`: ```xml <management-notification-address>activemq.notifications</management-notification-address> @@ -645,195 +688,186 @@ Topic notificationsTopic = ActiveMQJMSClient.createTopic("activemq.notifications Session session = ... MessageConsumer notificationConsumer = session.createConsumer(notificationsTopic); -notificationConsumer.setMessageListener(new MessageListener() -{ - public void onMessage(Message notif) - { - System.out.println("------------------------"); - System.out.println("Received notification:"); - try - { - Enumeration propertyNames = notif.getPropertyNames(); - while (propertyNames.hasMoreElements()) - { - String propertyName = (String)propertyNames.nextElement(); - System.out.format(" %s: %s\n", propertyName, notif.getObjectProperty(propertyName)); - } - } - catch (JMSException e) - { - } - System.out.println("------------------------"); +notificationConsumer.setMessageListener(new MessageListener() { + public void onMessage(Message notif) { + System.out.println("------------------------"); + System.out.println("Received notification:"); + try { + Enumeration propertyNames = notif.getPropertyNames(); + while (propertyNames.hasMoreElements()) { + String propertyName = (String)propertyNames.nextElement(); + System.out.format(" %s: %s\n", propertyName, notif.getObjectProperty(propertyName)); + } + } catch (JMSException e) { + } + System.out.println("------------------------"); } }); ``` ### Example -See the [Examples](examples.md) chapter for an example which shows how to use a JMS `MessageListener` to receive management notifications from ActiveMQ Artemis server. +See the [Management Notification Example](examples.md#management-notification) +which shows how to use a JMS `MessageListener` to receive management +notifications from ActiveMQ Artemis server. ### Notification Types and Headers -Below is a list of all the different kinds of notifications as well as -which headers are on the messages. Every notification has a -`_AMQ_NotifType` (value noted in parentheses) and `_AMQ_NotifTimestamp` -header. The timestamp is the un-formatted result of a call to -`java.lang.System.currentTimeMillis()`. +Below is a list of all the different kinds of notifications as well as which +headers are on the messages. Every notification has a `_AMQ_NotifType` (value +noted in parentheses) and `_AMQ_NotifTimestamp` header. The timestamp is the +un-formatted result of a call to `java.lang.System.currentTimeMillis()`. -- `BINDING_ADDED` (0) +- `BINDING_ADDED` (0) - `_AMQ_Binding_Type`, `_AMQ_Address`, `_AMQ_ClusterName`, - `_AMQ_RoutingName`, `_AMQ_Binding_ID`, `_AMQ_Distance`, - `_AMQ_FilterString` + `_AMQ_Binding_Type`, `_AMQ_Address`, `_AMQ_ClusterName`, + `_AMQ_RoutingName`, `_AMQ_Binding_ID`, `_AMQ_Distance`, + `_AMQ_FilterString` -- `BINDING_REMOVED` (1) +- `BINDING_REMOVED` (1) - `_AMQ_Address`, `_AMQ_ClusterName`, `_AMQ_RoutingName`, - `_AMQ_Binding_ID`, `_AMQ_Distance`, `_AMQ_FilterString` + `_AMQ_Address`, `_AMQ_ClusterName`, `_AMQ_RoutingName`, + `_AMQ_Binding_ID`, `_AMQ_Distance`, `_AMQ_FilterString` -- `CONSUMER_CREATED` (2) +- `CONSUMER_CREATED` (2) - `_AMQ_Address`, `_AMQ_ClusterName`, `_AMQ_RoutingName`, `_AMQ_Distance`, - `_AMQ_ConsumerCount`, `_AMQ_User`, `_AMQ_RemoteAddress`, - `_AMQ_SessionName`, `_AMQ_FilterString` + `_AMQ_Address`, `_AMQ_ClusterName`, `_AMQ_RoutingName`, `_AMQ_Distance`, + `_AMQ_ConsumerCount`, `_AMQ_User`, `_AMQ_RemoteAddress`, + `_AMQ_SessionName`, `_AMQ_FilterString` -- `CONSUMER_CLOSED` (3) +- `CONSUMER_CLOSED` (3) - `_AMQ_Address`, `_AMQ_ClusterName`, `_AMQ_RoutingName`, `_AMQ_Distance`, - `_AMQ_ConsumerCount`, `_AMQ_User`, `_AMQ_RemoteAddress`, - `_AMQ_SessionName`, `_AMQ_FilterString` + `_AMQ_Address`, `_AMQ_ClusterName`, `_AMQ_RoutingName`, `_AMQ_Distance`, + `_AMQ_ConsumerCount`, `_AMQ_User`, `_AMQ_RemoteAddress`, + `_AMQ_SessionName`, `_AMQ_FilterString` -- `SECURITY_AUTHENTICATION_VIOLATION` (6) +- `SECURITY_AUTHENTICATION_VIOLATION` (6) - `_AMQ_User` + `_AMQ_User` -- `SECURITY_PERMISSION_VIOLATION` (7) +- `SECURITY_PERMISSION_VIOLATION` (7) - `_AMQ_Address`, `_AMQ_CheckType`, `_AMQ_User` + `_AMQ_Address`, `_AMQ_CheckType`, `_AMQ_User` -- `DISCOVERY_GROUP_STARTED` (8) +- `DISCOVERY_GROUP_STARTED` (8) - `name` + `name` -- `DISCOVERY_GROUP_STOPPED` (9) +- `DISCOVERY_GROUP_STOPPED` (9) - `name` + `name` -- `BROADCAST_GROUP_STARTED` (10) +- `BROADCAST_GROUP_STARTED` (10) - `name` + `name` -- `BROADCAST_GROUP_STOPPED` (11) +- `BROADCAST_GROUP_STOPPED` (11) - `name` + `name` -- `BRIDGE_STARTED` (12) +- `BRIDGE_STARTED` (12) - `name` + `name` -- `BRIDGE_STOPPED` (13) +- `BRIDGE_STOPPED` (13) - `name` + `name` -- `CLUSTER_CONNECTION_STARTED` (14) +- `CLUSTER_CONNECTION_STARTED` (14) - `name` + `name` -- `CLUSTER_CONNECTION_STOPPED` (15) +- `CLUSTER_CONNECTION_STOPPED` (15) - `name` + `name` -- `ACCEPTOR_STARTED` (16) +- `ACCEPTOR_STARTED` (16) - `factory`, `id` + `factory`, `id` -- `ACCEPTOR_STOPPED` (17) +- `ACCEPTOR_STOPPED` (17) - `factory`, `id` + `factory`, `id` -- `PROPOSAL` (18) +- `PROPOSAL` (18) - `_JBM_ProposalGroupId`, `_JBM_ProposalValue`, `_AMQ_Binding_Type`, - `_AMQ_Address`, `_AMQ_Distance` + `_JBM_ProposalGroupId`, `_JBM_ProposalValue`, `_AMQ_Binding_Type`, + `_AMQ_Address`, `_AMQ_Distance` -- `PROPOSAL_RESPONSE` (19) +- `PROPOSAL_RESPONSE` (19) - `_JBM_ProposalGroupId`, `_JBM_ProposalValue`, - `_JBM_ProposalAltValue`, `_AMQ_Binding_Type`, `_AMQ_Address`, - `_AMQ_Distance` + `_JBM_ProposalGroupId`, `_JBM_ProposalValue`, + `_JBM_ProposalAltValue`, `_AMQ_Binding_Type`, `_AMQ_Address`, + `_AMQ_Distance` -- `CONSUMER_SLOW` (21) +- `CONSUMER_SLOW` (21) - `_AMQ_Address`, `_AMQ_ConsumerCount`, `_AMQ_RemoteAddress`, - `_AMQ_ConnectionName`, `_AMQ_ConsumerName`, `_AMQ_SessionName` + `_AMQ_Address`, `_AMQ_ConsumerCount`, `_AMQ_RemoteAddress`, + `_AMQ_ConnectionName`, `_AMQ_ConsumerName`, `_AMQ_SessionName` ## Message Counters -Message counters can be used to obtain information on queues *over time* -as Apache ActiveMQ Artemis keeps a history on queue metrics. +Message counters can be used to obtain information on queues *over time* as +Apache ActiveMQ Artemis keeps a history on queue metrics. -They can be used to show *trends* on queues. For example, using the -management API, it would be possible to query the number of messages in -a queue at regular interval. However, this would not be enough to know -if the queue is used: the number of messages can remain constant because -nobody is sending or receiving messages from the queue or because there -are as many messages sent to the queue than messages consumed from it. -The number of messages in the queue remains the same in both cases but -its use is widely different. +They can be used to show *trends* on queues. For example, using the management +API, it would be possible to query the number of messages in a queue at regular +interval. However, this would not be enough to know if the queue is used: the +number of messages can remain constant because nobody is sending or receiving +messages from the queue or because there are as many messages sent to the queue +than messages consumed from it. The number of messages in the queue remains +the same in both cases but its use is widely different. Message counters give additional information about the queues: -- `count` +- `count` - The *total* number of messages added to the queue since the server - was started + The *total* number of messages added to the queue since the server was + started -- `countDelta` +- `countDelta` - the number of messages added to the queue *since the last message - counter update* + the number of messages added to the queue *since the last message counter + update* -- `messageCount` +- `messageCount` - The *current* number of messages in the queue + The *current* number of messages in the queue -- `messageCountDelta` +- `messageCountDelta` - The *overall* number of messages added/removed from the queue *since - the last message counter update*. For example, if - `messageCountDelta` is equal to `-10` this means that overall 10 - messages have been removed from the queue (e.g. 2 messages were - added and 12 were removed) + The *overall* number of messages added/removed from the queue *since the last + message counter update*. For example, if `messageCountDelta` is equal to `-10` + this means that overall 10 messages have been removed from the queue (e.g. 2 + messages were added and 12 were removed) -- `lastAddTimestamp` +- `lastAddTimestamp` - The timestamp of the last time a message was added to the queue + The timestamp of the last time a message was added to the queue -- `udpateTimestamp` +- `udpateTimestamp` - The timestamp of the last message counter update + The timestamp of the last message counter update -These attributes can be used to determine other meaningful data as well. -For example, to know specifically how many messages were *consumed* from -the queue since the last update simply subtract the `messageCountDelta` -from `countDelta`. + These attributes can be used to determine other meaningful data as well. For + example, to know specifically how many messages were *consumed* from the queue + since the last update simply subtract the `messageCountDelta` from + `countDelta`. ### Configuring Message Counters -By default, message counters are disabled as it might have a small -negative effect on memory. +By default, message counters are disabled as it might have a small negative +effect on memory. -To enable message counters, you can set it to `true` in -`broker.xml`: +To enable message counters, you can set it to `true` in `broker.xml`: ```xml <message-counter-enabled>true</message-counter-enabled> ``` -Message counters keep a history of the queue metrics (10 days by -default) and sample all the queues at regular interval (10 seconds by -default). If message counters are enabled, these values should be -configured to suit your messaging use case in -`broker.xml`: +Message counters keep a history of the queue metrics (10 days by default) and +sample all the queues at regular interval (10 seconds by default). If message +counters are enabled, these values should be configured to suit your messaging +use case in `broker.xml`: ```xml <!-- keep history for a week --> @@ -842,8 +876,8 @@ configured to suit your messaging use case in <message-counter-sample-period>60000</message-counter-sample-period> ``` -Message counters can be retrieved using the Management API. For example, -to retrieve message counters on a queue using JMX: +Message counters can be retrieved using the Management API. For example, to +retrieve message counters on a queue using JMX: ```java // retrieve a connection to Apache ActiveMQ Artemis's MBeanServer @@ -863,4 +897,5 @@ messageCounter.getMessageCountDelta()); ### Example -See the [Examples](examples.md) chapter for an example which shows how to use message counters to retrieve information on a queue. +See the [Message Counter Example](examples.md#message-counter) which shows how +to use message counters to retrieve information on a queue.
http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/masking-passwords.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/masking-passwords.md b/docs/user-manual/en/masking-passwords.md index 4ec64ba..c7332c7 100644 --- a/docs/user-manual/en/masking-passwords.md +++ b/docs/user-manual/en/masking-passwords.md @@ -1,65 +1,67 @@ # Masking Passwords -By default all passwords in Apache ActiveMQ Artemis server's configuration files are in -plain text form. This usually poses no security issues as those files -should be well protected from unauthorized accessing. However, in some -circumstances a user doesn't want to expose its passwords to more eyes -than necessary. +By default all passwords in Apache ActiveMQ Artemis server's configuration +files are in plain text form. This usually poses no security issues as those +files should be well protected from unauthorized accessing. However, in some +circumstances a user doesn't want to expose its passwords to more eyes than +necessary. Apache ActiveMQ Artemis can be configured to use 'masked' passwords in its -configuration files. A masked password is an obscure string -representation of a real password. To mask a password a user will use an -'encoder'. The encoder takes in the real password and outputs the masked -version. A user can then replace the real password in the configuration -files with the new masked password. When Apache ActiveMQ Artemis loads a masked -password, it uses a suitable 'decoder' to decode it into real password. +configuration files. A masked password is an obscure string representation of a +real password. To mask a password a user will use an 'encoder'. The encoder +takes in the real password and outputs the masked version. A user can then +replace the real password in the configuration files with the new masked +password. When Apache ActiveMQ Artemis loads a masked password, it uses a +suitable 'decoder' to decode it into real password. -Apache ActiveMQ Artemis provides a default password encoder and decoder. Optionally -users can use or implement their own encoder and decoder for masking the -passwords. +Apache ActiveMQ Artemis provides a default password encoder and decoder. +Optionally users can use or implement their own encoder and decoder for masking +the passwords. -In general, a masked password can be identified using one of two ways. The first one -is the ENC() syntax, i.e. any string value wrapped in ENC() is to be treated as -a masked password. For example +In general, a masked password can be identified using one of two ways. The +first one is the `ENC()` syntax, i.e. any string value wrapped in `ENC()` is to +be treated as a masked password. For example `ENC(xyz)` The above indicates that the password is masked and the masked value is `xyz`. -The ENC() syntax is the preferred way to indicating a masked password and is +The `ENC()` syntax is the **preferred way** of masking a password and is universally supported in every password configuration in Artemis. -The other way is to use a `mask-password` attribute to tell that a password -in a configuration file should be treated as 'masked'. For example: +The other way is to use a `mask-password` attribute to tell that a password in +a configuration file should be treated as 'masked'. For example: ```xml <mask-password>true</mask-password> <cluster-password>xyz</cluster-password> ``` -This method is now deprecated and exists only to maintain backward-compatibility. -Newer configurations may not support it. + +This method is now **deprecated** and exists only to maintain +backward-compatibility. Newer configurations may not support it. ### Password Masking in Server Configuration File #### General Masking Configuration -Besides supporting the ENC() syntax, the server configuration file (i.e. broker.xml) -has a property that defines the default masking behaviors over the entire file scope. +Besides supporting the `ENC()` syntax, the server configuration file (i.e. +broker.xml) has a property that defines the default masking behaviors over the +entire file scope. -`mask-password`: this boolean type property indicates if a password -should be masked or not. Set it to "true" if you want your passwords -masked. The default value is "false". +`mask-password`: this boolean type property indicates if a password should be +masked or not. Set it to "true" if you want your passwords masked. The default +value is "false". `password-codec`: this string type property identifies the name of the class which will be used to decode the masked password within the broker. If not -specified then the default `org.apache.activemq.artemis.utils.DefaultSensitiveStringCodec` -will be used. +specified then the default +`org.apache.activemq.artemis.utils.DefaultSensitiveStringCodec` will be used. #### Specific Masking Behaviors ##### cluster-password -If it is specified in ENC() syntax it will be treated as masked, or +If it is specified in `ENC()` syntax it will be treated as masked, or If `mask-password` is `true` the `cluster-password` will be treated as masked. @@ -73,76 +75,77 @@ will have different password masking needs. When a `connector` or `acceptor` is initialised, Apache ActiveMQ Artemis will add the aforementioned `mask-password` and `password-codec` values to the -`connector` or `acceptor` parameters using the keys `activemq.usemaskedpassword` -and `activemq.passwordcodec` respectively. The Netty and InVM implementations -will use these as needed and any other implementations will have access to -these to use if they so wish. +`connector` or `acceptor` parameters using the keys +`activemq.usemaskedpassword` and `activemq.passwordcodec` respectively. The +Netty and InVM implementations will use these as needed and any other +implementations will have access to these to use if they so wish. -The preferred way, however, is to use the ENC() syntax. +The preferred way, however, is to use the `ENC()` syntax. ##### Core Bridges -Core Bridges are configured in the server configuration file and so the -masking of its `password` properties follows the same rules as that of -`cluster-password`. It supports ENC() syntax. +Core Bridges are configured in the server configuration file and so the masking +of its `password` properties follows the same rules as that of +`cluster-password`. It supports `ENC()` syntax. -For using `mask-password` property, the following table summarizes the +For using `mask-password` property, the following table summarizes the relations among the above-mentioned properties - mask-password | cluster-password | acceptor/connector passwords | bridge password - :------------- | :---------------- | :--------------------------- | :--------------- - absent | plain text | plain text | plain text - false | plain text | plain text | plain text - true | masked | masked | masked +mask-password | cluster-password | acceptor/connector passwords | bridge password +--- | --- | --- | --- +absent|plain text|plain text|plain text +false|plain text|plain text|plain text +true|masked|masked|masked -It is recommended that you use the `ENC()` syntax for new applications/deployments. +It is recommended that you use the `ENC()` syntax for new +applications/deployments. #### Examples -Note: In the following examples if related attributed or properties are +**Note:** In the following examples if related attributed or properties are absent, it means they are not specified in the configure file. -example 1 +- Unmasked -```xml -<cluster-password>bbc</cluster-password> -``` + ```xml + <cluster-password>bbc</cluster-password> + ``` -This indicates the cluster password is a plain text value ("bbc"). + This indicates the cluster password is a plain text value `bbc`. -example 2 +- Masked 1 -```xml -<cluster-password>ENC(xyz)</cluster-password> -``` + ```xml + <cluster-password>ENC(xyz)</cluster-password> + ``` -This indicates the cluster password is a masked value ("xyz"). + This indicates the cluster password is a masked value `xyz`. -example 3 +- Masked 2 -```xml -<mask-password>true</mask-password> -<cluster-password>80cf731af62c290</cluster-password> -``` + ```xml + <mask-password>true</mask-password> + <cluster-password>80cf731af62c290</cluster-password> + ``` -This indicates the cluster password is a masked value and Apache ActiveMQ Artemis will -use its built-in decoder to decode it. All other passwords in the -configuration file, Connectors, Acceptors and Bridges, will also use -masked passwords. + This indicates the cluster password is a masked value and Apache ActiveMQ + Artemis will use its built-in decoder to decode it. All other passwords in the + configuration file, Connectors, Acceptors and Bridges, will also use masked + passwords. #### Passwords in bootstrap.xml The broker embeds a web-server for hosting some web applications such as a -management console. It is configured in bootstrap.xml as a web -component. The web server can be secured using https protocol, and it can be -configured with a keystore password and/or truststore password which by -default are specified in plain text forms. +management console. It is configured in bootstrap.xml as a web component. The +web server can be secured using https protocol, and it can be configured with a +keystore password and/or truststore password which by default are specified in +plain text forms. -To mask these passwords you need to use ENC() syntax. The `mask-password` is -not supported here. +To mask these passwords you need to use `ENC()` syntax. The `mask-password` +boolean is not supported here. -You can also set the `passwordCodec` attribute if you want to use a password codec -other than the default one. For example +You can also set the `passwordCodec` attribute if you want to use a password +codec other than the default one. For example ```xml <web bind="https://localhost:8443"; path="web" @@ -154,24 +157,23 @@ other than the default one. For example ### Passwords for the JCA Resource Adapter -Both ra.xml and MDB activation configuration have a `password` property -that can be masked preferably using ENC() syntax. +Both ra.xml and MDB activation configuration have a `password` property that +can be masked preferably using `ENC()` syntax. -Alternatively it can use a optional attribute in ra.xml to indicate that a password -is masked: +Alternatively it can use a optional attribute in ra.xml to indicate that a +password is masked: -`UseMaskedPassword` -- If setting to "true" the passwords are masked. -Default is false. +`UseMaskedPassword` -- If setting to "true" the passwords are masked. Default +is false. There is another property in ra.xml that can specify a codec: -`PasswordCodec` -- Class name and its parameters for the Decoder used to -decode the masked password. Ignored if UseMaskedPassword is false. The -format of this property is a full qualified class name optionally -followed by key/value pairs. It is the same format as that for JMS -Bridges. Example: +`PasswordCodec` -- Class name and its parameters for the Decoder used to decode +the masked password. Ignored if UseMaskedPassword is false. The format of this +property is a full qualified class name optionally followed by key/value pairs. +It is the same format as that for JMS Bridges. Example: -Example 1 Using the ENC() syntax: +Example 1 Using the `ENC()` syntax: ```xml <config-property> @@ -206,16 +208,17 @@ Example 2 Using the "UseMaskedPassword" property: </config-property> ``` -With this configuration, both passwords in ra.xml and all of its MDBs -will have to be in masked form. +With this configuration, both passwords in ra.xml and all of its MDBs will have +to be in masked form. ### Passwords in artemis-users.properties Apache ActiveMQ Artemis's built-in security manager uses plain properties files -where the user passwords are specified in a hashed form by default. Note, the passwords -are technically *hashed* rather than masked in this context. The default `PropertiesLoginModule` -will not decode the passwords in `artemis-users.properties` but will instead hash the input -and compare the two hashed values for password verification. +where the user passwords are specified in a hashed form by default. Note, the +passwords are technically *hashed* rather than masked in this context. The +default `PropertiesLoginModule` will not decode the passwords in +`artemis-users.properties` but will instead hash the input and compare the two +hashed values for password verification. Please use Artemis CLI command to add a password. For example: @@ -223,26 +226,27 @@ Please use Artemis CLI command to add a password. For example: ./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` +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. -Passwords in `artemis-users.properties` are automatically detected as hashed or not -by looking for the syntax `ENC(<hash>)`. The `mask-password` parameter does not need -to be `true` to use hashed passwords here. +Passwords in `artemis-users.properties` are automatically detected as hashed or +not by looking for the syntax `ENC(<hash>)`. The `mask-password` parameter does +not need to be `true` to use hashed passwords here. ### Password in login.config -Artemis supports LDAP login modules to be configured in JAAS configuration -file (default name is `login.config`). When connecting to a LDAP server usually -you need to supply a connection password in the config file. By default this +Artemis supports LDAP login modules to be configured in JAAS configuration file +(default name is `login.config`). When connecting to a LDAP server usually you +need to supply a connection password in the config file. By default this password is in plain text form. -To mask it you need to configure the passwords in your login module -using ENC() syntax. To specify a codec using the following property: +To mask it you need to configure the passwords in your login module using +`ENC()` syntax. To specify a codec using the following property: -`passwordCodec` - the password codec class name. (the default codec -will be used if it is absent) +`passwordCodec` - the password codec class name. (the default codec will be +used if it is absent) For example: @@ -270,24 +274,24 @@ LDAPLoginExternalPasswordCodec { ### Choosing a decoder for password masking -As described in the previous sections, all password masking requires a -decoder. A decoder uses an algorithm to convert a masked password into -its original clear text form in order to be used in various security -operations. The algorithm used for decoding must match that for -encoding. Otherwise the decoding may not be successful. +As described in the previous sections, all password masking requires a decoder. +A decoder uses an algorithm to convert a masked password into its original +clear text form in order to be used in various security operations. The +algorithm used for decoding must match that for encoding. Otherwise the +decoding may not be successful. For user's convenience Apache ActiveMQ Artemis provides a default decoder. However a user can implement their own if they wish. #### The Default Decoder -Whenever no decoder is specified in the configuration file, the default -decoder is used. The class name for the default decoder is -`org.apache.activemq.artemis.utils.DefaultSensitiveStringCodec`. It has hashing, -encoding, and decoding capabilities. It uses `java.crypto.Cipher` utilities -to hash or encode a plaintext password and also to decode a masked string using -same algorithm and key. Using this decoder/encoder is pretty straightforward. To -get a mask for a password, just run the `mask` command: +Whenever no decoder is specified in the configuration file, the default decoder +is used. The class name for the default decoder is +`org.apache.activemq.artemis.utils.DefaultSensitiveStringCodec`. It has +hashing, encoding, and decoding capabilities. It uses `java.crypto.Cipher` +utilities to hash or encode a plaintext password and also to decode a masked +string using same algorithm and key. Using this decoder/encoder is pretty +straightforward. To get a mask for a password, just run the `mask` command: ```sh ./artemis mask <plaintextPassword> @@ -304,18 +308,19 @@ plaintext password in broker.xml with it. #### Using a custom decoder -It is possible to use a custom decoder rather than the built-in one. -Simply make sure the decoder is in Apache ActiveMQ Artemis's classpath. The custom decoder -can also be service loaded rather than class loaded, if the decoder's service provider is installed in the classpath. -Then configure the server to use it as follows: +It is possible to use a custom decoder rather than the built-in one. Simply +make sure the decoder is in Apache ActiveMQ Artemis's classpath. The custom +decoder can also be service loaded rather than class loaded, if the decoder's +service provider is installed in the classpath. Then configure the server to +use it as follows: ```xml <password-codec>com.foo.SomeDecoder;key1=value1;key2=value2</password-codec> ``` -If your decoder needs params passed to it you can do this via key/value -pairs when configuring. For instance if your decoder needs say a -"key-location" parameter, you can define like so: +If your decoder needs params passed to it you can do this via key/value pairs +when configuring. For instance if your decoder needs say a "key-location" +parameter, you can define like so: ```xml <password-codec>com.foo.NewDecoder;key-location=/some/url/to/keyfile</password-codec> @@ -328,15 +333,14 @@ Then configure your cluster-password like this: ``` When Apache ActiveMQ Artemis reads the cluster-password it will initialize the -NewDecoder and use it to decode "mask\_password". It also process all -passwords using the new defined decoder. +NewDecoder and use it to decode "mask\_password". It also process all passwords +using the new defined decoder. #### Implementing Custom Codecs -To use a different decoder than the built-in one, you either pick one -from existing libraries or you implement it yourself. All decoders must -implement the `org.apache.activemq.artemis.utils.SensitiveDataCodec<T>` -interface: +To use a different decoder than the built-in one, you either pick one from +existing libraries or you implement it yourself. All decoders must implement +the `org.apache.activemq.artemis.utils.SensitiveDataCodec<T>` interface: ```java public interface SensitiveDataCodec<T> @@ -347,8 +351,8 @@ public interface SensitiveDataCodec<T> } ``` -This is a generic type interface but normally for a password you just -need String type. So a new decoder would be defined like +This is a generic type interface but normally for a password you just need +String type. So a new decoder would be defined like ```java public class MyNewDecoder implements SensitiveDataCodec<String> @@ -367,4 +371,5 @@ public class MyNewDecoder implements SensitiveDataCodec<String> ``` Last but not least, once you get your own decoder please [add it to the -classpath](using-server.md#adding-runtime-dependencies) otherwise the broker will fail to load it! \ No newline at end of file +classpath](using-server.md#adding-runtime-dependencies) otherwise the broker +will fail to load it! http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/maven-plugin.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/maven-plugin.md b/docs/user-manual/en/maven-plugin.md index 19bda2f..143db9d 100644 --- a/docs/user-manual/en/maven-plugin.md +++ b/docs/user-manual/en/maven-plugin.md @@ -13,17 +13,17 @@ You could for example use these maven plugins on your testsuite or deployment au There are three goals that you can use -- create +- `create` -This will create a server accordingly to your arguments. You can do some extra tricks here such as installing extra libraries for external modules. + This will create a server accordingly to your arguments. You can do some extra tricks here such as installing extra libraries for external modules. -- cli +- `cli` -This will perform any CLI operation. This is basically a maven expression of the CLI classes + This will perform any CLI operation. This is basically a maven expression of the CLI classes -- runClient +- `runClient` -This is a simple wrapper around classes implementing a static main call. Notice that this won't spawn a new VM or new Thread. + This is a simple wrapper around classes implementing a static main call. Notice that this won't spawn a new VM or new Thread. ## Declaration @@ -31,11 +31,14 @@ This is a simple wrapper around classes implementing a static main call. Notice On your pom, use the plugins section: ```xml - <build> - <plugins> - <plugin> - <groupId>org.apache.activemq</groupId> - <artifactId>artemis-maven-plugin</artifactId> +<build> + <plugins> + <plugin> + <groupId>org.apache.activemq</groupId> + <artifactId>artemis-maven-plugin</artifactId> + </plugin> + </plugins> +</build> ``` ## create goal @@ -43,7 +46,7 @@ On your pom, use the plugins section: I won't detail every operation of the create plugin here, but I will try to describe the main parameters: Name | Description -:--- | :--- +--- | --- configuration | A place that will hold any file to replace on the configuration. For instance if you are providing your own broker.xml. Default is "${basedir}/target/classes/activemq/server0" home | The location where you downloaded and installed artemis. Default is "${activemq.basedir}" alternateHome | This is used case you have two possible locations for your home (e.g. one under compile and one under production @@ -54,16 +57,15 @@ liblist[] | A list of libraries to be installed under ./lib. ex: "org.jgroups:jg Example: ```xml -<executions> - <execution> - <id>create</id> - <goals> - <goal>create</goal> - </goals> - <configuration> - <ignore>${noServer}</ignore> - </configuration> - </execution> +<execution> + <id>create</id> + <goals> + <goal>create</goal> + </goals> + <configuration> + <ignore>${noServer}</ignore> + </configuration> +</execution> ``` @@ -72,7 +74,7 @@ Example: Some properties for the CLI Name | Description -:--- | :--- +--- | --- configuration | A place that will hold any file to replace on the configuration. For instance if you are providing your own broker.xml. Default is "${basedir}/target/classes/activemq/server0" home | The location where you downloaded and installed artemis. Default is "${activemq.basedir}" alternateHome | This is used case you have two possible locations for your home (e.g. one under compile and one under production @@ -105,7 +107,7 @@ Example: This is a simple solution for running classes implementing the main method. Name | Description -:--- | :--- +--- | --- clientClass | A class implement a static void main(String arg[]) args | A string array of arguments passed to the method http://git-wip-us.apache.org/repos/asf/activemq-artemis/blob/40b66d13/docs/user-manual/en/message-expiry.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/message-expiry.md b/docs/user-manual/en/message-expiry.md index 99cb73f..68463f5 100644 --- a/docs/user-manual/en/message-expiry.md +++ b/docs/user-manual/en/message-expiry.md @@ -2,19 +2,19 @@ Messages can be set with an optional *time to live* when sending them. -Apache ActiveMQ Artemis will not deliver a message to a consumer after it's time to -live has been exceeded. If the message hasn't been delivered by the time -that time to live is reached the server can discard it. +Apache ActiveMQ Artemis will not deliver a message to a consumer after it's +time to live has been exceeded. If the message hasn't been delivered by the +time that time to live is reached the server can discard it. -Apache ActiveMQ Artemis's addresses can be assigned a expiry address so that, when -messages are expired, they are removed from the queue and sent to the -expiry address. Many different queues can be bound to an expiry address. -These *expired* messages can later be consumed for further inspection. +Apache ActiveMQ Artemis's addresses can be assigned a expiry address so that, +when messages are expired, they are removed from the queue and sent to the +expiry address. Many different queues can be bound to an expiry address. These +*expired* messages can later be consumed for further inspection. ## Core API -Using Apache ActiveMQ Artemis Core API, you can set an expiration time directly on the -message: +Using Apache ActiveMQ Artemis Core API, you can set an expiration time directly +on the message: ```java // message will expire in 5000ms from now @@ -28,23 +28,23 @@ JMS MessageProducer allows to set a TimeToLive for the messages it sent: producer.setTimeToLive(5000); ``` -Expired messages which are consumed from an expiry address have the -following properties: +Expired messages which are consumed from an expiry address have the following +properties: -- `_AMQ_ORIG_ADDRESS` +- `_AMQ_ORIG_ADDRESS` - a String property containing the *original address* of the expired - message + a String property containing the *original address* of the expired + message -- `_AMQ_ORIG_QUEUE` +- `_AMQ_ORIG_QUEUE` - a String property containing the *original queue* of the expired - message + a String property containing the *original queue* of the expired + message -- `_AMQ_ACTUAL_EXPIRY` +- `_AMQ_ACTUAL_EXPIRY` - a Long property containing the *actual expiration time* of the - expired message + a Long property containing the *actual expiration time* of the + expired message ## Configuring Expiry Addresses @@ -57,29 +57,29 @@ Expiry address are defined in the address-setting configuration: </address-setting> ``` -If messages are expired and no expiry address is specified, messages are -simply removed from the queue and dropped. Address wildcards can be used -to configure expiry address for a set of addresses (see [Understanding the Wildcard Syntax](wildcard-syntax.md)). +If messages are expired and no expiry address is specified, messages are simply +removed from the queue and dropped. Address [wildcards](wildcard-syntax.md) can +be used to configure expiry address for a set of addresses. ## Configuring The Expiry Reaper Thread -A reaper thread will periodically inspect the queues to check if -messages have expired. +A reaper thread will periodically inspect the queues to check if messages have +expired. The reaper thread can be configured with the following properties in `broker.xml` -- `message-expiry-scan-period` +- `message-expiry-scan-period` - How often the queues will be scanned to detect expired messages (in - milliseconds, default is 30000ms, set to `-1` to disable the reaper - thread) + How often the queues will be scanned to detect expired messages (in + milliseconds, default is 30000ms, set to `-1` to disable the reaper thread) -- `message-expiry-thread-priority` +- `message-expiry-thread-priority` - The reaper thread priority (it must be between 1 and 10, 10 being the - highest priority, default is 3) + The reaper thread priority (it must be between 1 and 10, 10 being the highest + priority, default is 3) ## Example -See the [examples.md](examples.md) chapter for an example which shows how message expiry is configured and used with JMS. +See the [Message Expiration Example](examples.md#message-expiration) which +shows how message expiry is configured and used with JMS.
