ARTEMIS-1360 Documenting runtime reloadable configuration
Adding details about broker's configuration parameters that can be reloaded during runtime.
This commit is contained in:
Howard Gao
Clebert Suconic
parent
0df12657af
commit
9a9976bd31
|
|
@ -26,3 +26,219 @@ Deletion of Address's and Queue's, not auto created is controlled by Address Set
|
|||
By default both settings are OFF as such address & queues won't be removed upon reload, given the risk of losing messages.
|
||||
|
||||
When OFF You may execute explicit CLI or Management operations to remove address & queues.
|
||||
|
||||
## Configuration Parameters that are reloaded at runtime
|
||||
|
||||
The broker configuration file has 2 main parts, `<core>` and `<jms>`. Some of the parameters in the 2 parts are monitored and,
|
||||
if modified, reloaded into the broker at runtime.
|
||||
|
||||
Please note that elements under `<jms>` are deprecated. Users are encouraged to use `<core>` configuration entities.
|
||||
|
||||
> *Note:*
|
||||
> Most parameters reloaded take effect immediately after reloading. However there are some
|
||||
> that won’t take any effect unless you restarting the broker.
|
||||
> Such parameters are specifically indicated in the following text.
|
||||
|
||||
### Parameters in `<core>` that can be reloaded at runtime
|
||||
|
||||
#### Parameters under `<security-settings>`
|
||||
|
||||
* `<security-setting>` element
|
||||
|
||||
Changes to any <security-setting> elements will be reloaded. Each <security-setting> defines security roles for a matched address.
|
||||
|
||||
* The `match` attribute
|
||||
|
||||
This attribute defines the address for which the security-setting is defined. It can take wildcards such as ‘#’ and ‘*’.
|
||||
|
||||
* The `<permission>` sub-elements
|
||||
|
||||
Each `<security-setting>` can have a list of `<permission>` elements, each of which defines a specific permission-roles mapping.
|
||||
Each permission has 2 attributes ‘type’ and ‘roles’. The ‘type’ attribute defines the type of operation allowed, the ‘roles’
|
||||
defines which roles are allowed to perform such operation. Refer to the user’s manual for a list of operations that can be defined.
|
||||
|
||||
> *Note:*
|
||||
> Once loaded the security-settings will take effect immediately. Any new clients will subject
|
||||
> to the new security settings. Any existing clients will subject to the new settings as well, as soon as they performs
|
||||
> a new security-sensitive operation.
|
||||
|
||||
Below lists the effects of adding, deleting and updating of an element/attribute within the `<security-settings>` element, whether
|
||||
an change can be done or can’t be done.
|
||||
|
||||
Operation | Add | Delete | Update
|
||||
:--- | :--- | :--- | :---
|
||||
`<security-settings>` | X* (at most one element is allowed) | Deleting it means delete the whole security settings from the running broker. | N/A*
|
||||
`<security-setting>` | Adding one element means adding a new set of security roles for an address in the running broker | Deleting one element means removing a set of security roles for an address in the running broker | Updating one element means updating the security roles for an address (if match attribute is not changed), or means removing the old match address settings and adding a new one (if match attribute is changed)
|
||||
attribute `match` | N/A* | X* | Changing this value is same as deleting the whole <security-setting> with the old match value and adding
|
||||
`<permission>` | Adding one means adding a new permission definition to runtime broker | Deleting a permission from the runtime broker | Updating a permission-roles in the runtime broker
|
||||
attribute `type` | N/A* | X* | Changing the type value means remove the permission of the old one and add the permission of this type to the running broker.
|
||||
attribute `roles` | N/A* | X* | Changing the ‘roles’ value means updating the permission’s allowed roles to the running broker
|
||||
|
||||
> * `N/A` means this operation is not applicable.
|
||||
> * `X` means this operation is not allowed.
|
||||
|
||||
#### Parameters under `<address-settings>`
|
||||
|
||||
* `<address-settings>` element
|
||||
|
||||
Changes to elements under `<address-settings>` will be reloaded into runtime broker. It contains a list of `<address-setting>` elements.
|
||||
|
||||
* `<address-setting>` element
|
||||
|
||||
Each address-setting element has a ‘match’ attribute that defines an address pattern for which this address-setting is defined. It also has a list of sub-elements used to define the properties of a matching address.
|
||||
|
||||
> *Note:*
|
||||
> Parameters reloaded in this category will take effect immediately after reloading. The effect of deletion of Address's and Queue's,
|
||||
> not auto created is controlled by parameter `config-delete-addresses` and `config-delete-queues` as described in the doc.
|
||||
|
||||
Below lists the effects of adding, deleting and updating of an element/attribute within the address-settings element, whether an change
|
||||
can be done or can’t be done.
|
||||
|
||||
Operation | Add | Delete | Update
|
||||
:--- | :--- | :--- | :---
|
||||
`<address-settings>` | X(at most one element is allowed) | Deleting it means delete the whole address settings from the running broker | N/A
|
||||
`<address-setting>` | Adding one element means adding a set of address-setting for a new address in the running broker | Deleting one means removing a set of address-setting for an address in the running broker | Updating one element means updating the address setting for an address (if match attribute is not changed), or means removing the old match address settings and adding a new one (if match attribute is changed)
|
||||
attribute `match` | N/A | X | Changing this value is same as deleting the whole <address-setting> with the old match value and adding a new one with the new match value.
|
||||
`<dead-letter-address>` | X (no more than one can be present) | Removing the configured dead-letter-address address from running broker. | The dead letter address of the matching address will be updated after reloading
|
||||
`<expiry-address>` | X (no more than one can be present) | Removing the configured expiry address from running broker. | The expiry address of the matching address will be updated after reloading
|
||||
`<expiry-delay>` | X (no more than one can be present) | The configured expiry-delay will be removed from running broker. | The expiry-delay for the matching address will be updated after reloading.
|
||||
`<redelivery-delay>` | X (no more than one can be present) | The configured redelivery-delay will be removed from running broker after reloading | The redelivery-delay for the matchin address will be updated after reloading.
|
||||
`<redelivery-delay-multiplier>` | X (no more than one can be present) | The configured redelivery-delay-multiplier will be removed from running broker after reloading. | The redelivery-delay-multiplier will be updated after reloading.
|
||||
`<max-redelivery-delay>` | X (no more than one can be present) | The configured max-redelivery-delay will be removed from running broker after reloading. | The max-redelivery-delay will be updated after reloading.
|
||||
`<max-delivery-attempts>` | X (no more than one can be present) | The configured max-delivery-attempts will be removed from running broker after reloading. | The max-delivery-attempts will be updated after reloading.
|
||||
`<max-size-bytes>` | X (no more than one can be present) | The configured max-size-bytes will be removed from running broker after reloading. | The max-size-bytes will be updated after reloading.
|
||||
`<page-size-bytes>` | X (no more than one can be present) | The configured page-size-bytes will be removed from running broker after reloading. | The page-size-bytes will be updated after reloading.
|
||||
`<page-max-cache-size>` | X (no more than one can be present) | The configured page-max-cache-size will be removed from running broker after reloading. | The page-max-cache-size will be updated after reloading.
|
||||
`<address-full-policy>` | X (no more than one can be present) | The configured address-full-policy will be removed from running broker after reloading. | The address-full-policy will be updated after reloading.
|
||||
`<message-counter-history-day-limit>` | X (no more than one can be present) | The configured message-counter-history-day-limit will be removed from running broker after reloading. | The message-counter-history-day-limit will be updated after reloading.
|
||||
`<last-value-queue>` | X (no more than one can be present) | The configured last-value-queue will be removed from running broker after reloading (no longer a last value queue). | The last-value-queue will be updated after reloading.
|
||||
`<redistribution-delay>` | X (no more than one can be present) | The configured redistribution-delay will be removed from running broker after reloading. | The redistribution-delay will be updated after reloading.
|
||||
`<send-to-dla-on-no-route>` | X (no more than one can be present) | The configured send-to-dla-on-no-route will be removed from running broker after reloading. | The send-to-dla-on-no-route will be updated after reloading.
|
||||
`<slow-consumer-threshold>` | X (no more than one can be present) | The configured slow-consumer-threshold will be removed from running broker after reloading. | The slow-consumer-threshold will be updated after reloading.
|
||||
`<slow-consumer-policy>` | X (no more than one can be present) | The configured slow-consumer-policy will be removed from running broker after reloading. | The slow-consumer-policy will be updated after reloading.
|
||||
`<slow-consumer-check-period>` | X (no more than one can be present) | The configured slow-consumer-check-period will be removed from running broker after reloading. (meaning the slow consumer checker thread will be cancelled) | The slow-consumer-check-period will be updated after reloading.
|
||||
`<auto-create-queues>` | X (no more than one can be present) | The configured auto-create-queues will be removed from running broker after reloading. | The auto-create-queues will be updated after reloading.
|
||||
`<auto-delete-queues>` | X (no more than one can be present) | The configured auto-delete-queues will be removed from running broker after reloading. | The auto-delete-queues will be updated after reloading.
|
||||
`<config-delete-queues>` | X (no more than one can be present) | The configured config-delete-queues will be removed from running broker after reloading. | The config-delete-queues will be updated after reloading.
|
||||
`<auto-create-addresses>` | X (no more than one can be present) | The configured auto-create-addresses will be removed from running broker after reloading. | The auto-create-addresses will be updated after reloading.
|
||||
`<auto-delete-addresses>` | X (no more than one can be present) | The configured auto-delete-addresses will be removed from running broker after reloading. | The auto-delete-addresses will be updated after reloading.
|
||||
`<config-delete-addresses>` | X (no more than one can be present) | The configured config-delete-addresses will be removed from running broker after reloading. | The config-delete-addresses will be updated after reloading.
|
||||
`<management-browse-page-size>` | X (no more than one can be present) | The configured management-browse-page-size will be removed from running broker after reloading. | The management-browse-page-size will be updated after reloading.
|
||||
`<default-purge-on-no-consumers>` | X (no more than one can be present) | The configured default-purge-on-no-consumers will be removed from running broker after reloading. | The default-purge-on-no-consumers will be updated after reloading.
|
||||
`<default-max-consumers>` | X (no more than one can be present) | The configured default-max-consumers will be removed from running broker after reloading. | The default-max-consumers will be updated after reloading.
|
||||
`<default-queue-routing-type>` | X (no more than one can be present) | The configured default-queue-routing-type will be removed from running broker after reloading. | The default-queue-routing-type will be updated after reloading.
|
||||
`<default-address-routing-type>` | X (no more than one can be present) | The configured default-address-routing-type will be removed from running broker after reloading. | The default-address-routing-type will be updated after reloading.
|
||||
|
||||
|
||||
#### Parameters under `<diverts>`
|
||||
|
||||
All `<divert>` elements will be reloaded. Each `<divert>` element
|
||||
has a ‘name’ and several sub-elements that defines the properties of a divert.
|
||||
|
||||
> *Note:*
|
||||
> Reloading `<diverts>` only resulting in deploying new diverts. Existing diverts
|
||||
> won’t get undeployed even if you delete a `<divert>` element. Nor an existing
|
||||
> divert will be updated if its element is updated after reloading.
|
||||
> To make this happen you need a restart of the broker.
|
||||
|
||||
Below lists the effects of adding, deleting and updating of an element/attribute
|
||||
within the diverts element, whether an change can be done or can’t be done.
|
||||
|
||||
Operation | Add | Delete | Update
|
||||
:--- | :--- | :--- | :---
|
||||
`<diverts>` | X (no more than one can be present) | Deleting it means delete (undeploy) all diverts in running broker. | N/A
|
||||
`<divert>` | Adding a new divert. It will be deployed after reloading | No effect on the deployed divert.(unless restarting broker, in which case the divert will no longer be deployed) | No effect on the deployed divert (unless restarting broker, in which case the divert will be redeployed)
|
||||
attribute `name` | N/A | X | A new divert with the name will be deployed. (if it is not already there in broker). Otherwise no effect.
|
||||
`<transformer-class-name>` | X (no more than one can be present) | No effect on the deployed divert.(unless restarting broker, in which case the divert will be deployed without the transformer class) | No effect on the deployed divert.(unless restarting broker, in which case the divert has the transformer class)
|
||||
`<exclusive>` | X (no more than one can be present) | No effect on the deployed divert.(unless restarting broker) | No effect on the deployed divert.(unless restarting broker)
|
||||
`<routing-name>` | X (no more than one can be present) | No effect on the deployed divert.(unless restarting broker) | No effect on the deployed divert.(unless restarting broker)
|
||||
`<address>` | X (no more than one can be present) | No effect on the deployed divert.(unless restarting broker) | No effect on the deployed divert.(unless restarting broker)
|
||||
`<forwarding-address>` | X (no more than one can be present) | No effect on the deployed divert.(unless restarting broker) | No effect on the deployed divert.(unless restarting broker)
|
||||
`<filter>` | X (no more than one can be present) | No effect on the deployed divert.(unless restarting broker) | No effect on the deployed divert.(unless restarting broker)
|
||||
`<routing-type>` | X (no more than one can be present) | No effect on the deployed divert.(unless restarting broker) | No effect on the deployed divert.(unless restarting broker)
|
||||
|
||||
#### Parameters under `<addresses>`
|
||||
|
||||
The `<addresses>` element contains a list `<address>` elements. Once changed, all `<address>` elements
|
||||
in `<addresses>` will be reloaded.
|
||||
|
||||
> *Note:*
|
||||
> Once reloaded, all new addresses (as well as the pre-configured queues) will be
|
||||
> deployed to the running broker and all those that are missing from the configuration will be undeployed.
|
||||
|
||||
> *Note:*
|
||||
> Parameters reloaded in this category will take effect immediately after reloading.
|
||||
> The effect of deletion of Address's and Queue's, not auto created is controlled by
|
||||
> parameter `config-delete-addresses` and `config-delete-queues` as described in this doc.
|
||||
|
||||
Below lists the effects of adding, deleting and updating of an element/attribute
|
||||
within the `<addresses>` element, whether an change can be done or can’t be done.
|
||||
|
||||
Operation | Add | Delete | Update
|
||||
:--- | :--- | :--- | :---
|
||||
`<addresses>` | X(no more than one is present) | Deleting it means delete (undeploy) all diverts in running broker. | N/A
|
||||
`<address>` | A new address will be deployed in the running broker | The corresponding address will be undeployed. | N/A
|
||||
attribute `name` | N/A | X | After reloading the address of the old name will be undeployed and the new will be deployed.
|
||||
`<anycast>` | X(no more than one is present) | The anycast routing type will be undeployed from this address, as well as its containing queues after reloading | N/A
|
||||
`<queue>`(under `<anycast>`) | A anycast queue will be deployed after reloading | The anycast queue will be undeployed | For updating queues please see next section `<queues>`
|
||||
`<multicast>` | X(no more than one is present) | The multicast routing type will be undeployed from this address, as well as its containing queues after reloading | N/A
|
||||
`<queue>`(under `<multicast>`) | A multicast queue will be deployed after reloading | The multicast queue will be undeployed | For updating queues please see next section `<queues>`
|
||||
|
||||
#### Parameters under `<queues>`
|
||||
|
||||
The `<queues>` element contains a list `<queue>` elements. Once changed, all `<queue>` elements in `<queues>` will be reloaded.
|
||||
|
||||
> *Note:*
|
||||
> Once reloaded, all new queues will be deployed to the running broker and all
|
||||
> queues that are missing from the configuration will be undeployed.
|
||||
> *Note:*
|
||||
> Parameters reloaded in this category will take effect immediately after reloading.
|
||||
> The effect of deletion of Address's and Queue's, not auto created is controlled by
|
||||
> parameter `config-delete-addresses` and `config-delete-queues` as described in this doc.
|
||||
|
||||
Below lists the effects of adding, deleting and updating of an element/attribute within the `<queues>` element,
|
||||
and whether an change can be done or can’t be done.
|
||||
|
||||
Operation | Add | Delete | Update
|
||||
:--- | :--- | :--- | :---
|
||||
`<queues>` | X(no more than one is present) | Deleting it means delete (undeploy) all queues from running broker. | N/A
|
||||
`<queue>` | A new queue is deployed after reloading | The queue will be undeployed after reloading. | N/A
|
||||
attribute `name` | N/A | X | A queue with new name will be deployed and the queue with old name will be updeployed after reloading (see Note above).
|
||||
attribute `max-consumers` | N/A | No effect unless starting broker | No effect unless starting broker
|
||||
attribute `purge-on-no-consumers` | N/A | No effect unless starting broker | No effect unless starting broker
|
||||
attribute `address` | N/A | No effect unless starting broker | No effect unless starting broker
|
||||
attribute `filter` | N/A | No effect unless starting broker | No effect unless starting broker
|
||||
attribute `durable` | N/A | No effect unless starting broker | No effect unless starting broker
|
||||
|
||||
### Parameters in `<jms>` that can be reloaded at runtime *(Deprecated)*
|
||||
|
||||
#### The `<queue>` elements
|
||||
|
||||
Changes to any `<queue>` elements will be reloaded to the running broker.
|
||||
|
||||
> *Note:*
|
||||
> Once reloaded, new queues defined in the new changes will be deployed to the running
|
||||
> broker. However existing queues won’t get undeployed even if the matching element is
|
||||
> deleted/missing. Also new queue elements matching existing queues won’t get re-created – they remain unchanged.
|
||||
|
||||
Operation | Add | Delete | Update
|
||||
:--- | :--- | :--- | :---
|
||||
`<queue>` | A new jms queue will be deployed after reloading | No effect unless starting broker | No effect unless starting broker
|
||||
attribute `<name>` | N/A | X | A jms queue of the new name will be deployed after reloading
|
||||
`<selector>` | X(no more than one is present) | No effect unless starting broker | No effect unless starting broker
|
||||
`<durable>` | X(no more than one is present) | No effect unless starting broker | No effect unless starting broker
|
||||
|
||||
#### The `<topic>` elements
|
||||
|
||||
Changes to any `<topic>` elements will be reloaded to the running broker.
|
||||
|
||||
> *Note:*
|
||||
> Once reloaded, new topics defined in the new changes will be deployed to
|
||||
> the running broker. However existing topics won’t get undeployed even if the
|
||||
> matching element is deleted/missing. Also any `<topic>` elements matching
|
||||
> existing topics won’t get re-deployed – they remain unchanged.
|
||||
|
||||
Operation | Add | Delete | Update
|
||||
:--- | :--- | :--- | :---
|
||||
`<topic>` | A new jms topic will be deployed after reloading | No effect unless starting broker | No effect unless starting broker
|
||||
attribute `name` | N/A | X | A jms topic of the new name will be deployed after reloading
|
||||
|
|
|
|||
Loading…
Reference in New Issue