This is an automated email from the ASF dual-hosted git repository. robbie pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/activemq-artemis.git
commit 7320db7e51da2b67f021e292dfc922e74d8ae238 Author: Justin Bertram <[email protected]> AuthorDate: Wed Sep 25 10:18:04 2024 -0500 ARTEMIS-5057 fill in missing config index + other doc updates --- .../resources/schema/artemis-configuration.xsd | 38 ++++----- docs/user-manual/configuration-index.adoc | 97 +++++++++++++++++++++- docs/user-manual/core-bridges.adoc | 6 +- docs/user-manual/data-retention.adoc | 12 ++- docs/user-manual/security.adoc | 23 ++++- 5 files changed, 145 insertions(+), 31 deletions(-) diff --git a/artemis-server/src/main/resources/schema/artemis-configuration.xsd b/artemis-server/src/main/resources/schema/artemis-configuration.xsd index 4905b77f98..afd809ad1a 100644 --- a/artemis-server/src/main/resources/schema/artemis-configuration.xsd +++ b/artemis-server/src/main/resources/schema/artemis-configuration.xsd @@ -600,7 +600,7 @@ <xsd:element name="journal-retention-directory" maxOccurs="1" minOccurs="0"> <xsd:annotation> <xsd:documentation> - the directory to store journal-retention message in and rention configuraion. + where to keep retained data including attributes for how long to keep it (unit and period) and how much to keep (storage-limit) </xsd:documentation> </xsd:annotation> <xsd:complexType> @@ -636,7 +636,7 @@ Notice we first remove files based on period and if you're using more storage then you configured we start removing older files. By default this is unlimited (not filled). - Supports byte notation like "K", "Mb", "MiB", "GB", etc. + Supports byte notation like "K", "MB", "MiB", "GB", etc. </xsd:documentation> </xsd:annotation> </xsd:attribute> @@ -685,7 +685,7 @@ </xsd:annotation> </xsd:element> - <xsd:element name="journal-device-block-size" type="xsd:long" maxOccurs="1" minOccurs="0"> + <xsd:element name="journal-device-block-size" type="xsd:long" default="4096" maxOccurs="1" minOccurs="0"> <xsd:annotation> <xsd:documentation> The size in bytes used by the device. This is usually translated as fstat/st_blksize @@ -698,7 +698,7 @@ <xsd:annotation> <xsd:documentation> The size (in bytes) of the internal buffer on the journal. - Supports byte notation like "K", "Mb", "MiB", "GB", etc. + Supports byte notation like "K", "MB", "MiB", "GB", etc. </xsd:documentation> </xsd:annotation> </xsd:element> @@ -733,7 +733,7 @@ <xsd:annotation> <xsd:documentation> The size (in bytes) of each journal file. - Supports byte notation like "K", "Mb", "MiB", "GB", etc. + Supports byte notation like "K", "MB", "MiB", "GB", etc. </xsd:documentation> </xsd:annotation> </xsd:element> @@ -809,7 +809,7 @@ <xsd:documentation> Size (in bytes) before all addresses will enter into their Full Policy configured upon messages being produced. - Supports byte notation like "K", "Mb", "MiB", "GB", etc. + Supports byte notation like "K", "MB", "MiB", "GB", etc. </xsd:documentation> </xsd:annotation> </xsd:element> @@ -827,7 +827,7 @@ <xsd:annotation> <xsd:documentation> Min free bytes on disk below which the system blocks or fails clients. Supports byte notation like - "K", "Mb", "GB", etc. Will override max-disk-usage if both are set. + "K", "MB", "GB", etc. Will override max-disk-usage if both are set. </xsd:documentation> </xsd:annotation> </xsd:element> @@ -1429,7 +1429,7 @@ <xsd:annotation> <xsd:documentation> Any message larger than this size (in bytes) is considered a large message (to be sent in chunks). - Supports byte notation like "K", "Mb", "MiB", "GB", etc. + Supports byte notation like "K", "MB", "MiB", "GB", etc. </xsd:documentation> </xsd:annotation> </xsd:element> @@ -1514,7 +1514,7 @@ <xsd:annotation> <xsd:documentation> Once the bridge has received this many bytes, it sends a confirmation. - Supports byte notation like "K", "Mb", "MiB", "GB", etc. + Supports byte notation like "K", "MB", "MiB", "GB", etc. </xsd:documentation> </xsd:annotation> </xsd:element> @@ -1523,7 +1523,7 @@ <xsd:annotation> <xsd:documentation> Producer flow control. - Supports byte notation like "K", "Mb", "MiB", "GB", etc. + Supports byte notation like "K", "MB", "MiB", "GB", etc. </xsd:documentation> </xsd:annotation> </xsd:element> @@ -2469,7 +2469,7 @@ <xsd:annotation> <xsd:documentation> Messages larger than this are considered large-messages. - Supports byte notation like "K", "Mb", "MiB", "GB", etc. + Supports byte notation like "K", "MB", "MiB", "GB", etc. </xsd:documentation> </xsd:annotation> </xsd:element> @@ -2567,7 +2567,7 @@ <xsd:annotation> <xsd:documentation> The size (in bytes) of the window used for confirming data from the server connected to. - Supports byte notation like "K", "Mb", "MiB", "GB", etc. + Supports byte notation like "K", "MB", "MiB", "GB", etc. </xsd:documentation> </xsd:annotation> </xsd:element> @@ -2576,7 +2576,7 @@ <xsd:annotation> <xsd:documentation> Producer flow control. - Supports byte notation like "K", "Mb", "MiB", "GB", etc. + Supports byte notation like "K", "MB", "MiB", "GB", etc. </xsd:documentation> </xsd:annotation> </xsd:element> @@ -2912,7 +2912,7 @@ <xsd:annotation> <xsd:documentation> The max page size (in bytes) to use for all addresses when using JDBC. - Supports byte notation like "K", "Mb", "MiB", "GB", etc. + Supports byte notation like "K", "MB", "MiB", "GB", etc. </xsd:documentation> </xsd:annotation> </xsd:element> @@ -3941,7 +3941,7 @@ <xsd:documentation> the maximum size (in bytes) for an address (-1 means no limits). This is used in PAGING, BLOCK and FAIL policies. - Supports byte notation like "K", "Mb", "MiB", "GB", etc. + Supports byte notation like "K", "MB", "MiB", "GB", etc. </xsd:documentation> </xsd:annotation> </xsd:element> @@ -3958,7 +3958,7 @@ <xsd:annotation> <xsd:documentation> After the address enters into page mode, this attribute will configure how many pages can be written into page before activating the page-full-policy. - Supports byte notation like "K", "Mb", "MiB", "GB", etc. + Supports byte notation like "K", "MB", "MiB", "GB", etc. </xsd:documentation> </xsd:annotation> </xsd:element> @@ -3986,7 +3986,7 @@ <xsd:annotation> <xsd:documentation> The page size (in bytes) to use for an address. - Supports byte notation like "K", "Mb", "MiB", "GB", etc. + Supports byte notation like "K", "MB", "MiB", "GB", etc. </xsd:documentation> </xsd:annotation> </xsd:element> @@ -4588,7 +4588,7 @@ <xsd:element name="connector-services"> <xsd:annotation> <xsd:documentation> - a list of connector services + DEPRECATED: a list of connector services </xsd:documentation> </xsd:annotation> <xsd:complexType> @@ -4604,7 +4604,7 @@ <xsd:element maxOccurs="1" minOccurs="1" name="factory-class" type="xsd:string"> <xsd:annotation> <xsd:documentation> - Name of the factory class of the ConnectorService + DEPRECATED: Name of the factory class of the ConnectorService </xsd:documentation> </xsd:annotation> </xsd:element> diff --git a/docs/user-manual/configuration-index.adoc b/docs/user-manual/configuration-index.adoc index c3083bde44..72f962c8f6 100644 --- a/docs/user-manual/configuration-index.adoc +++ b/docs/user-manual/configuration-index.adoc @@ -252,6 +252,11 @@ This is a list | The amount in bytes before all addresses are considered full. | Half of the JVM's `-Xmx` +| xref:paging.adoc#global-max-messages[global-max-messages] +| Number of messages before all addresses will enter into their Full Policy configured. +It works in conjunction with global-max-size, being watever value hits its maximum first. +| `-1` + | xref:graceful-shutdown.adoc#graceful-server-shutdown[graceful-shutdown-enabled] | true means that graceful shutdown is enabled. | `false` @@ -345,14 +350,30 @@ The system will create as many files as needed however when reclaiming files it | the type of journal to use. | `ASYNCIO` +| xref:data-retention.adoc#data-retention[journal-retention-directory] +| where to keep retained data including attributes for how long to keep it (`unit` & `period`) and how much to keep (`storage-limit`) +| n/a + | xref:persistence.adoc#configuring-the-message-journal[journal-datasync] | It will use msync/fsync on journal operations. | `true` +| journal-device-block-size +| The size in bytes used by the storage device. This is usually translated as `fstat`/`st_blksize`, and this is a way to bypass the value returned as `st_blksize`. +| `4096` + +| log-journal-write-rate +| Whether to log messages about the journal write rate. +| `false` + | xref:large-messages.adoc#large-messages[large-messages-directory] | the directory to store large messages. | `data/largemessages` +| xref:large-messages.adoc#configuring-the-server[large-message-sync] +| should sync large messages before closing the file +| `true` + | log-delegate-factory-class-name | *deprecated* the name of the factory class to use for log delegation. | n/a @@ -379,9 +400,16 @@ If set to "true" the passwords are masked. | xref:paging.adoc#max-disk-usage[max-disk-usage] | The max percentage of data we should use from disks. The broker will block while the disk is full. -Disable by setting -1. +Disable by setting `-1`. | 90 +| xref:paging.adoc#minimum-disk-free[min-disk-free] +| Min free bytes on disk below which the system blocks or fails clients. +Supports byte notation like "K", "MB", "GB", etc. +Will override `max-disk-usage` if both are set. +Disable by setting `-1`. +| `-1` + | xref:perf-tuning.adoc#performance-tuning[memory-measure-interval] | frequency to sample JVM memory in ms (or -1 to disable memory sampling). | -1 @@ -487,14 +515,22 @@ In most cases this should be set to '1'. | Maximum number of threads to use for the scheduled thread pool. | 5 -| xref:security.adoc#authentication-authorization[security-enabled] +| xref:security.adoc#basic-configuration[security-enabled] | true means that security is enabled. | `true` -| xref:security.adoc#authentication-authorization[security-invalidation-interval] +| xref:security.adoc#caching-security-operations[security-invalidation-interval] | how long (in ms) to wait before invalidating the security cache. | 10000 +| xref:security.adoc#caching-security-operations[authentication-cache-size] +| how large to make the authentication cache +| 1000 + +| xref:security.adoc#caching-security-operations[authorization-cache-size] +| how large to make the authorization cache +| 1000 + | system-property-prefix | Prefix for replacing configuration settings using Bean Utils. | n/a @@ -507,6 +543,10 @@ In most cases this should be set to '1'. | whether or not to add the name of the validated user to the messages that user sends. | `false` +| xref:security.adoc#tracking-the-validated-user[reject-empty-validated-user] +| true means that the server will not allow any message that doesn't have a validated user, in JMS this is `JMSXUserID` +| `false` + | xref:security.adoc#role-based-security-for-addresses[security-settings] | <<security-setting-type,a list of security-setting>>. | n/a @@ -604,6 +644,57 @@ in your security-settings. | [[management-rbac-prefix]] management-rbac-prefix | parameter to configure the prefix for security-settings match addresses to control RBAC on xref:management.adoc#jmx-authorization-in-broker-xml[JMX MBean operations] and optionally on xref:management.adoc#fine-grained-rbac-on-management-messages[management messages] | mops (shorthand for management operations) + +| xref:address-model.adoc#temporary-queues[temporary-queue-namespace] +| the namespace to use for looking up address settings for temporary queues +| n/a + +| xref:mqtt.adoc#automatic-subscription-clean-up[mqtt-session-scan-interval] +| how often (in ms) to scan for expired MQTT sessions +| `5000` + +| xref:mqtt.adoc#persistent-subscriptions[mqtt-session-state-persistence-timeout] +| how long (in ms) to wait to persist MQTT session state +| `5000` + +| xref:federation.adoc#federation[federations] +| a list of federation elements +| n/a + +| xref:connection-routers.adoc#connection-routers[connection-routers] +| a list of connection-router elements +| n/a + +| mirror-ack-manager-queue-attempts +| The number of times a mirror target would retry an acknowledgement on the queue before scanning page files for the message. +| `5` + +| mirror-ack-manager-page-attempts +| The number of times a mirror target would retry an acknowledgement on paging. +| `2` + +| mirror-ack-manager-retry-delay +| Period in milliseconds for which retries are going to be exercised. +| `100` + +| mirror-page-transaction +| Should Mirror use Page Transactions When target destinations is paging? +When a target queue on the mirror is paged, the mirror will not record a page transaction for every message. +The default is `false`, and the overhead of paged messages will be smaller, but there is a possibility of eventual duplicates in case of interrupted communication between the mirror source and target. +If you set this to `true` there will be a record stored on the journal for the page-transaction additionally to the record in the page store. +| `false` + +| xref:management.adoc#suppressing-session-notifications[suppress-session-notifications] +| Whether to suppress `SESSION_CREATED` and `SESSION_CLOSED` notifications. +Set to `true` to reduce notification overhead. +However, these are required to enforce unique client ID utilization in a cluster for MQTT clients. +| `false` + +| xref:address-settings.adoc#literal-matches[literal-match-markers] +| The characters that mark a "literal" match. +A literal match means the setting(s) will only apply to the exact match regardless of wildcards. +If this setting is not omitted then it must be two characters - the start marker and the end marker. +| n/a |=== == address-setting type diff --git a/docs/user-manual/core-bridges.adoc b/docs/user-manual/core-bridges.adoc index 84c150a490..672c67f010 100644 --- a/docs/user-manual/core-bridges.adoc +++ b/docs/user-manual/core-bridges.adoc @@ -102,7 +102,7 @@ See the xref:transformers.adoc#transformers[transformer chapter] for more detail min-large-message-size:: Any message larger than this size (in bytes) is considered a large message (to be sent in chunks). -Supports byte notation like "K", "Mb", "MiB", "GB", etc. +Supports byte notation like "K", "MB", "MiB", "GB", etc. Default is `102400` (i.e. 100KiB). check-period:: @@ -158,7 +158,7 @@ The default value for this parameter is `true`. confirmation-window-size:: This optional parameter determines the `confirmation-window-size` to use for the connection used to forward messages to the target node. -Supports byte notation like "K", "Mb", "MiB", "GB", etc. +Supports byte notation like "K", "MB", "MiB", "GB", etc. This attribute is described in section xref:client-failover.adoc#reconnection-and-failover-attributes[Client failover attributes] + [WARNING] @@ -169,7 +169,7 @@ When using the bridge to forward messages to an address which uses the `BLOCK` ` producer-window-size:: This optional parameter determines the producer flow control through the bridge. Use `-1` to disable. -Supports byte notation like "K", "Mb", "MiB", "GB", etc. +Supports byte notation like "K", "MB", "MiB", "GB", etc. Default is `1048576` (i.e. 1MiB). user:: diff --git a/docs/user-manual/data-retention.adoc b/docs/user-manual/data-retention.adoc index d51a20ec3a..30b349d0c0 100644 --- a/docs/user-manual/data-retention.adoc +++ b/docs/user-manual/data-retention.adoc @@ -2,13 +2,17 @@ :idprefix: :idseparator: - -If you enable `journal-retention` on broker.xml, ActiveMQ Artemis will keep copy of every data that has passed through the broker on this folder. +If you enable `journal-retention-directory` on broker.xml, ActiveMQ Artemis will keep copy of every data that has passed through the broker on this folder. [,xml] ---- - ... - <journal-retention unit="DAYS" directory="history" period="365" storage-limit="10G"/> - ... +<configuration...> + <core...> + ... + <journal-retention-directory unit="DAYS" period="365" storage-limit="10G">history</journal-retention-directory> + ... + </core> +</configuration> ---- ActiveMQ Artemis will keep a copy of each generated journal file, up to the configured retention period, at the unit chose. diff --git a/docs/user-manual/security.adoc b/docs/user-manual/security.adoc index 859af1aaa6..0d063e8f15 100644 --- a/docs/user-manual/security.adoc +++ b/docs/user-manual/security.adoc @@ -4,16 +4,31 @@ This chapter describes how security works with Apache ActiveMQ Artemis and how you can configure it. -To disable security completely simply set the `security-enabled` property to `false` in the `broker.xml` file. +== Basic Configuration + +Security is enabled by default. To disable security completely set the `security-enabled` property to `false` in the `broker.xml` file, e.g.: + +[,xml] +---- +<configuration...> + <core...> + ... + <security-enabled>false</security-enabled> + ... + </core> +</configuration> +---- + +== Caching Security Operations For performance reasons both *authentication and authorization is cached* independently. Entries are removed from the caches (i.e. invalidated) either when the cache reaches its maximum size in which case the least-recently used entry is removed or when an entry has been in the cache "too long". The size of the caches are controlled by the `authentication-cache-size` and `authorization-cache-size` configuration parameters. Both default to `1000`. +Using `0` will disable the corresponding cache. How long cache entries are valid is controlled by `security-invalidation-interval`, which is in milliseconds. -Using `0` will disable caching. The default is `10000` ms. == Tracking the Validated User @@ -25,6 +40,10 @@ For users authenticated based on their SSL certificate this name is the name to If `security-enabled` is `false` and `populate-validated-user` is `true` then the server will simply use whatever user name (if any) the client provides. This option is `false` by default. +It's also possible to set `reject-empty-validated-user`. +If `true` the server will reject any message that doesn't have a validated user. +This option is `false` by default. + == Role based security for addresses Apache ActiveMQ Artemis contains a flexible role-based security model for applying security to queues, based on their addresses. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected] For further information, visit: https://activemq.apache.org/contact
