555 lines
21 KiB
Plaintext
555 lines
21 KiB
Plaintext
= Configuration Reload
|
|
:idprefix:
|
|
:idseparator: -
|
|
|
|
The system will perform a periodic check on the configuration files, configured by `configuration-file-refresh-period`, with the default at `5000`, in milliseconds.
|
|
These checks can be disabled by specifying `-1`.
|
|
|
|
Note that the Log4J2 configuration has its own reload mechanism, configured via its own log4j2.properties file.
|
|
See xref:logging.adoc#configuration-reload[Logging configuration reload] for more detail.
|
|
|
|
Once the configuration file is changed (broker.xml) the following modules will be reloaded automatically:
|
|
|
|
* Address Settings
|
|
* Security Settings
|
|
* Diverts
|
|
* Addresses & Queues
|
|
* Bridges
|
|
|
|
If using xref:configuration-index.adoc#modularising-broker-xml[modularised `broker.xml`] ensure you also read xref:configuration-index.adoc#reloading-modular-configuration-files[reloading modular configuration files]
|
|
|
|
[NOTE]
|
|
====
|
|
Addresses, queues and diverts can be removed automatically when removed from the configuration:
|
|
|
|
config-delete-addresses::
|
|
* `OFF` (default) - will not remove the address upon config reload.
|
|
Messages left in the attached queues will be left intact.
|
|
* `FORCE` - will remove the address and its queues upon config reload.
|
|
Messages left in the attached queues will be *lost*.
|
|
|
|
config-delete-queues::
|
|
* `OFF` (default) - will not remove the queues upon config reload.
|
|
Messages left in the queues will be left intact.
|
|
* `FORCE` - will remove the queues.
|
|
Messages left in the queues will be *lost*.
|
|
|
|
config-delete-diverts::
|
|
* `OFF` (default) - will not remove the diverts upon config reload.
|
|
* `FORCE` - will remove the diverts upon config reload.
|
|
|
|
By default, all settings are `OFF`, so that addresses, queues and diverts aren't removed upon configuration reload, reducing the risk of losing messages.
|
|
|
|
Addresses, queues and diverts no longer present in the configuration file can be removed manually via the web interface, CLI, or JMX management operations.
|
|
====
|
|
|
|
== Reloadable Parameters
|
|
|
|
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.
|
|
|
|
NOTE: 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.
|
|
====
|
|
|
|
=== `<core>`
|
|
|
|
==== `<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 a 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 `</security-setting>`
|
|
|
|
| `<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.
|
|
====
|
|
|
|
==== `<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 a 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. `</address-setting>`
|
|
|
|
| `<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.
|
|
|
|
| `<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.
|
|
|===
|
|
|
|
==== `<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]
|
|
====
|
|
Existing diverts get undeployed if you delete their `<divert>` element.
|
|
====
|
|
|
|
Below lists the effects of adding, deleting and updating of an element/attribute within the diverts element, whether a 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
|
|
| Deleting it means the divert will be undeployed after reloading
|
|
| 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)
|
|
|===
|
|
|
|
==== `<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 a 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>`)
|
|
| An anycast queue will be deployed after reloading
|
|
| The anycast queue will be undeployed
|
|
| For updating queues please see next section `<queue>`
|
|
|
|
| `<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 `<queue>`
|
|
|===
|
|
|
|
==== `<queue>`
|
|
|
|
Changes to any `<queue>` elements will be reloaded to the running broker.
|
|
|
|
[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 `<queue>` element, and whether a change can be done or can't be done.
|
|
|
|
|===
|
|
| Operation | Add | Delete | Update
|
|
|
|
| `<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`
|
|
| If max-consumers > current consumers max-consumers will update on reload
|
|
| max-consumers will be set back to the default `-1`
|
|
| If max-consumers > current consumers max-consumers will update on reload
|
|
|
|
| attribute `purge-on-no-consumers`
|
|
| On reload purge-on-no-consumers will be updated
|
|
| Will be set back to the default `false`
|
|
| On reload purge-on-no-consumers will be updated
|
|
|
|
| attribute `enabled`
|
|
| On reload enabled will be updated
|
|
| Will be set back to the default `true`
|
|
| On reload enabled will be updated
|
|
|
|
| attribute `exclusive`
|
|
| On reload exclusive will be updated
|
|
| Will be set back to the default `false`
|
|
| On reload exclusive will be updated
|
|
|
|
| attribute `group-rebalance`
|
|
| On reload group-rebalance will be updated
|
|
| Will be set back to the default `false`
|
|
| On reload group-rebalance will be updated
|
|
|
|
| attribute `group-rebalance-pause-dispatch`
|
|
| On reload group-rebalance-pause-dispatch will be updated
|
|
| Will be set back to the default `false`
|
|
| On reload group-rebalance-pause-dispatch will be updated
|
|
|
|
| attribute `group-buckets`
|
|
| On reload group-buckets will be updated
|
|
| Will be set back to the default `-1`
|
|
| On reload group-buckets will be updated
|
|
|
|
| attribute `group-first-key`
|
|
| On reload group-first-key will be updated
|
|
| Will be set back to the default `null`
|
|
| On reload group-first-key will be updated
|
|
|
|
| attribute `last-value`
|
|
| On reload last-value will be updated
|
|
| Will be set back to the default `false`
|
|
| On reload last-value will be updated
|
|
|
|
| attribute `last-value-key`
|
|
| On reload last-value-key will be updated
|
|
| Will be set back to the default `null`
|
|
| On reload last-value-key will be updated
|
|
|
|
| attribute `non-destructive`
|
|
| On reload non-destructive will be updated
|
|
| Will be set back to the default `false`
|
|
| On reload non-destructive will be updated
|
|
|
|
| attribute `consumers-before-dispatch`
|
|
| On reload consumers-before-dispatch will be updated
|
|
| Will be set back to the default `0`
|
|
| On reload consumers-before-dispatch will be updated
|
|
|
|
| attribute `delay-before-dispatch`
|
|
| On reload delay-before-dispatch will be updated
|
|
| Will be set back to the default `-1`
|
|
| On reload delay-before-dispatch will be updated
|
|
|
|
| attribute `ring-size`
|
|
| On reload ring-size will be updated
|
|
| Will be set back to the default `-1`
|
|
| On reload ring-size will be updated
|
|
|
|
| `<filter>`
|
|
| The filter will be added after reloading
|
|
| The filter will be removed after reloading
|
|
| The filter will be updated after reloading
|
|
|
|
| `<durable>`
|
|
| The queue durability will be set to the given value after reloading
|
|
| The queue durability will be set to the default `true` after reloading
|
|
| The queue durability will be set to the new value after reloading
|
|
|
|
| `<user>`
|
|
| The queue user will be set to the given value after reloading
|
|
| The queue user will be set to the default `null` after reloading
|
|
| The queue user will be set to the new value after reloading
|
|
|===
|
|
|
|
=== `<jms>` _(Deprecated)_
|
|
|
|
=== `<queues>` _(Deprecated)_
|