System Properties

The system configuration can be maintained/supplied in three ways.

Configuration file

The most commonly and preferred way is to have an axonserver.properties or axonserver.yml file which contains the desired configuration parameters. The location of the file should be the current working directory or alternatively can be placed within a "config" subdirectory (relative to the current working directory).

An important note - In case both files are detected by Axon Server, it will read from both.

Command-line

In case the server is being started using “java –jar …”, you can also supply individual configuration properties with “-Dproperty=value”

Environment variables

Configuration values can also be supplied using environment variables. The parameter name should be all in upper case with any kebab-case(-) / camelCase and snake_case() substituted with _""_

Recommendations

There are some recommendations around Axon Server EE/SE configuration,

  • Use “./axonserver.properties” for common settings.

  • Use “./config/axonserver.properties” for environment/node-specific overrides.

  • Use “-D” or environment variables for one-time settings.

Configuration properties

A list of all the configuration properties by area is denoted below. Unless explicitly specified all property names are to be prefixed with "axoniq.axonserver"

Area Property Name Description Default Value

Node setup

name

Unique node name of the Axon Server node.

Hostname of the server

hostname

Hostname of the Axon Server node as communicated to clients.

Hostname of the server

internal-hostname

Hostname as communicated to other nodes of the cluster.

Hostname of the server

domain

Domain of this node as communicated to clients. Optional, if set will be appended to the hostname in communication with clients.

None

internal-domain

Domain as communicated to other nodes of the cluster.

"domain" value

port

gRPC port for the Axon Server node.

8124

server.port (no prefix)

HTTP port for the Axon Server console.

8024

internal-port

8224

tags

Key/value pairs of tags for tag based connections for clients.

None

devmode.enabled

(Axon SE only)

false

set-web-socket-allowed-origins

Set WebSocket CORS Allowed Origins.

false

web-socket-allowed-origins

List of WebSocket CORS Allowed Origins.

File Locations

event.storage

Path where (regular) events are stored as segmented files on disk.

./data directory

snapshot.storage

Path where Snapshot Events are stored as segmented files on disk.

./data directory

controldb-path

Path where Axon Server’s control database (axonserver-controldb) is created.

./data directory

controldb-backup-location

Location where the control DB backups are created.

.

pid-file-location

Location where AxonServer creates its pid file.

.

replication.log-storage-folder

Directory where the transaction logs for replication are stored.

./log directory

accesscontrol.token-dir

Directory where token is stored on startup.

./security directory

enterprise.license-directory

Directory where the license file can be found.

.

File Names

event.bloom-index-suffix

File suffix for bloom files

.bloom

event.events-suffix

File suffix for events files.

.events

event.index-suffix

File suffix for index files

.index

event.new-index-suffix

File suffix for new index files

.nindex

event.global-index-suffix

File suffix for global index files

.xref

snapshot.bloom-index-suffix

File suffix for snapshot bloom files

.sbloom

snapshot.events-suffix

File suffix for snapshot files

.snapshots

snapshot.index-suffix

File suffix for index files for snapshots

.sindex

replication.index-suffix

File suffix for index files for transaction logs

.index

replication.log-suffix

File suffix for transaction log files

.log

Event Store

event.bloom-index-fpp

False-positive percentage allowed for bloom index. Decreasing the value increases the size of the bloom indexes.

0.03

event.force-interval

Interval to force syncing files to disk (ms).

1000

event.primary-cleanup-delay

Delay to clear ByteBuffers from off-heap memory for writable segments.

15

event.secondary-cleanup-delay

Delay to clear ByteBuffers from off-heap memory for read-only segments.

15

event.segment-size

Size for new storage segments.

256Mb

event.sync-interval

Interval (ms) to check if there are files that are complete and can be closed.

1000

event.validation-segments

Number of segments to validate to on startup after unclean shutdown.

10

event.memory-mapped-segments

Number of recent segments that Axon Server keeps memory mapped.

5

event.events-per-segment-prefetch

Number of events to prefetch from disk when streaming events to the client.

50

snapshot.bloom-index-fpp

False-positive percentage allowed for bloom index for snapshots. Decreasing the value increases the size of the bloom indexes.

0.03

snapshot.force-interval

Interval to force syncing files to disk (ms).

1000

snapshot.primary-cleanup-delay

Delay to clear ByteBuffers from off-heap memory for writable segments.

15

snapshot.secondary-cleanup-delay

Delay to clear ByteBuffers from off-heap memory for read-only segments.

15

snapshot.segment-size

Size for new storage segments.

256Mb

snapshot.sync-interval

Interval (ms) to check if there are files that are complete and can be closed.

1000

snapshot.validation-segments

Number of snapshot segments to validate to on startup after unclean shutdown.

10

snapshot.memory-mapped-segments

Number of recent segments that Axon Server keeps memory mapped.

5

query.limit

200

new-permits-timeout

Timeout for event trackers while waiting for new permits.

120000

blacklisted-send-after

Force sending an event on an event tracker after this number of blacklisted events. Ensures that the token in the client application is updated.

1000

max-events-per-transaction

Maximum number of events that can be sent in a single transaction.

32767

enterprise.default-index-type

(Since 4.4.7, EE only) Sets the default index type to be used for new contexts. Values are JUMP_SKIP_INDEX and BLOOM_FILTER_INDEX.

JUMP_SKIP_INDEX

read-sequence-validation-strategy

(Since 4.4.14) Sets how to handle validation errors while reading aggregates from the event store. Values are LOG and FAIL.

LOG

event.use-mmap-index

By default, AxonServer will determine whether to use memory mapped indexes for event files in the event store based on operating system and java version, in rare cases it may be useful to override the default

event.force-clean-mmap-index

Option to forcefully close unused memory mapped files instead of leaving the garbage collector do this, by default, AxonServer will determine this based on operating system and java version, in rare cases it may be useful to override the default

event.aggregate.prefetch

Ensures that backpressure signals from clients are split into batches. The initial request amount is {prefetch}*5, and subsequent (or replenishing) request amount is {prefetch}

5

event.aggregate.retry.attempts

Number of retries for reading event aggregate stream.

3

event.aggregate.retry.delay

Delay (ms) between retries for reading event aggregate stream.

100

event.leader.retry.attempts

Number of retries for finding an event store.

3

event.leader.retry.delay

Delay (ms) between retries for finding an event store.

100

event-processor-permits-check

Delay (ms) between checking if tracking event processors are waiting for new permits for a long time.

2000

check-sequence-nr-for-snapshots

Whether to check for invalid sequence numbers on appending a snapshot.

true

Logging

logging.level.package_name (no prefix)

Change the logging level for specific packages or classes. (for example logging.level.io.axoniq.axonserver = INFO)

WARN level for all packages

logging.file.name (no prefix)

File name where log entries should be written to. Names can be an exact location or relative to the current directory. (for example logging.file.name = messaging.log)

stdout

logging.path (no prefix)

Location where log files should be created. Names can be an exact location or relative to the current directory. (for example logging.path = /var/log)

Cluster setup

autocluster.first

For auto cluster option, set to the internal host name for the first node in the cluster.

None

autocluster.contexts

For auto cluster option, defines the list of contexts to connect to or create.

None

SSL (Axon Server - HTTP Port)

security.require-ssl (No prefix)

Determines whether the server has ssl enabled on the HTTP port.

false

server.ssl.key-store-type (No prefix)

Keystore type. (should be PKCS12)

None

server.ssl.key-store (No prefix)

Location of the keystore.

None

server.ssl.key-store-password (No prefix)

Password to access the keystore.

None

server.ssl.key-alias (No prefix)

Alias to be used to access the keystore.

None

SSL (Axon Server - gRPC Port)

ssl.enabled

Determines whether the server has ssl enabled on the gRPC port.

false

ssl.cert-chain-file

Location of the public certificate file.

None

ssl.private-key-file

Location of the private key file.

None

ssl.internal-cert-chain-file

None

ssl.internal-trust-manager-file

None

ssl.internal-private-key-file

None

Access Control

accesscontrol.enabled

Indicates that access control is enabled for the server.

false

accesscontrol.cache-ttl

Timeout for authenticated tokens.

300000

accesscontrol.internal-token

accesscontrol.token

accesscontrol.admin-token

accesscontrol.systemtokenfile

File containing a predefined system token.

Messaging (Between Clients and Axon Server)

max-message-size

Maximum size of a message to be sent to the node.

4 MB

initial-nr-of-permits

Number of messages that the server can initially send to a client.

1000

nr-of-new-permits

Additional number of messages that the server can send to a client.

500

new-permits-threshold

When a client reaches this threshold in remaining messages, it sends a request with additional number of messages to receive.

500

force-connection-to-primary-or-messaging-node

Whether to force applications to connect to Primary nodes or Messaging Only nodes. When false, all nodes for a context are eligible to accept client connections.

false

instruction.result.timeout

Timeout in seconds for instruction results received via client server communication

10

Messaging (Between nodes of an Axon Server Cluster)

command-flow-control.initial-nr-of-permits

Number of command messages that the master can initially send to a replica.

10000

command-flow-control.nr-of-new-permits

Additional number of command messages that the master can send to replica.

5000

command-flow-control.new-permits-threshold

When a replica reaches this threshold in remaining command messages, it sends a request with this additional number of command messages to receive.

5000

query-flow-control.initial-nr-of-permits

Number of query messages that the master can initially send to a replica.

10000

query-flow-control.nr-of-new-permits

Additional number of query messages that the master can send to replica.

5000

query-flow-control.new-permits-threshold

When a replica reaches this threshold in remaining query messages, it sends a request with this additional number of query messages to receive.

5000

Replication

replication.flow-buffer

Number of unconfirmed append entry messages that may be sent to peer.

1000

replication.force-interval

Interval to force writes to disk.

1000

replication.force-snapshot-on-join

Option to force new members to first receive a snapshot when they join a cluster.

true

replication.heartbeat-timeout

Leader sends a heartbeat to followers if it has not sent any other messages to a follower for this time (in ms)

300

replication.initial-election-timeout

Extra time (in ms) that follower waits initially before moving to candidate state.

0

replication.log-compaction-enabled

Deletes old log files when all the entries in the file are applied for more than log-retention-hours hour.

true

replication.log-retention-hours

Time to keep log files after all entries have been applied.

1

replication.max-election-timeout

Maximal time (in ms.) that a follower waits before moving to candidate state, if it has not received any messages from a leader. Also, time that leader waits before stepping down if it has not heard from the majority of its followers.

2500

replication.max-entries-per-batch

Maximum number of append entry messages sent to one peer before moving to the next.

10

replication.max-indexes-in-memory

Number of index files for replication segments that Axon Server keeps in memory

10

storage.event.max-indexes-in-memory

Number of index files for event segments that Axon Server keeps in memory

50

snapshot.max-indexes-in-memory

Number of index files for snapshot segments that Axon Server keeps in memory

50

replication.max-replication-round

The number of attempts the log replication process will do during the replication a snapshot until the follower is caught up.

10

replication.max-snapshot-chunks-per-batch

Maximum number of objects that can be sent in a single install snapshot message

1000

replication.min-active-backups

When active backup nodes are added to a context, this indicates on how many active backup nodes transactions must be confirmed before the transaction is ready for commit.

1

replication.min-election-timeout

Minimal time (in ms.) that a follower waits before moving to candidate state, if it has not received any messages from a leader.

1000

replication.primary-cleanup-delay

Windows only. Delay before forcing the primary segment file from memory when no longer in use.

5

replication.secondary-cleanup-delay

Windows only. Delay before forcing the other segment files from memory when no longer in use.

30

replication.segment-size

Size of a transaction log file.

16 MB

replication.snapshot-flow-buffer

Number of unconfirmed install snapshot messages that may be sent to peer.

50

replication.sync-interval

Interval to check for files that can be closed.

1000

replication.wait-for-leader-timeout

Timeout (in ms.) to wait for leader when requesting access to event store while leader change in progress, if not set defaults to maxElectionTimeout.

-1

replication.use-mmap-index

By default, AxonServer will determine whether to use memory mapped indexes for replication logs based on operating system and java version, in rare cases it may be useful to override the default

replication.force-clean-mmap-index

Option to forcefully close unused memory mapped files instead of leaving the garbage collector do this, by default, AxonServer will determine this based on operating system and java version, in rare cases it may be useful to override the default

context-validation.rate

Rate of checks to verify that for each context, the corresponding replication group is ready for handling client requests.

5000

context-validation.initial-delay

Initial delay of checks to verify that for each context, the corresponding replication group is ready for handling client requests.

5000

Keep Alive

keep-alive-time

Interval at which AxonServer will send timeout messages. Set to 0 to disable gRPC timeout checks.

2500

keep-alive-timeout

Timeout (in ms.) for keep alive messages on gRPC connections.

5000

min-keep-alive-time

Minimum keep alive interval (in ms.) accepted by this end of the gRPC connection.

1000

client-heartbeat-timeout

Timeout (in ms.) on application level heartbeat between client and Axon Server.

5000

client-heartbeat-check-initial-delay

Initial time delay (in ms.) before Axon Server checks for heartbeats from clients.

10000

client-heartbeat-check-rate

How often (in ms.) does Axon Server check for heartbeats from clients.

1000

heartbeat.enabled

If this is set Axon Server will respond to heartbeats from clients and send heartbeat

false

client-heartbeat-frequency

Frequency (ms) for sending heartbeats

500

client-heartbeat-initial-delay

Initial delay (ms) for sending heartbeats

5000

Maintenance Tasks

cluster.connection-check-delay

Delay before the first run of the connection checker (in ms.)

1000

cluster.connection-check-interval

Interval between each run of the connection checker (in ms.)

1000

cluster.connection-wait-time

Timeout for connection request (in ms.)

3000

cluster.metrics-distribute-delay

Delay before the first run of the metrics distributor (in ms.)

1000

cluster.metrics-distribute-interval

Interval between each run of the metrics distributor (in ms.)

1000

cluster.rebalance-delay

Delay before the first run of the rebalancer (in seconds)

7

cluster.rebalance-interval

Interval between each run of the rebalancer (in seconds)

15

cluster.auto-balancing

Automatic rebalancing of client connections enabled.

true

cluster.balancing-rate

Rate at which rebalancing is attempted.

15000

cache-close-rate

Interval (in ms.) at which to check for timed out queries and commands.

5000

processor-info-timeout

Time in ms after which collected event processor info expires.

30000

enterprise.context-configuration-sync-rate

Rate of updating the status of pending configuration changes in raft group members

3600000

Performance

event.max-bloom-filters-in-memory

Maximum number of bloom filters to keep in memory

100

event.max-indexes-in-memory

Maximum number of indexes to keep open in memory

50

event.read-buffer-size

Size of the buffer when reading from non-memory mapped files. (SE only)

32KB

snapshot.max-bloom-filters-in-memory

Maximum number of bloom filters to keep in memory

100

snapshot.max-indexes-in-memory

Maximum number of indexes to keep open in memory

50

snapshot.read-buffer-size

Size of the buffer when reading from non-memory mapped files. (SE only)

32KB

snapshot.use-mmap-index

By default, AxonServer will determine whether to use memory mapped indexes for snapshot files in the event store based on operating system and java version, in rare cases it may be useful to override the default

snapshot.force-clean-mmap-index

Option to forcefully close unused memory mapped files instead of leaving the garbage collector do this, by default, AxonServer will determine this based on operating system and java version, in rare cases it may be useful to override the default

executor-thread-count

Number of threads for executing incoming gRPC requests

16

command-thread

Threads per client responsible for sending commands to the client.

1

query-thread

Threads per client responsible for sending queries to the client.

1

cluster-executor-thread-count

Number of threads for executing incoming gRPC requests for internal communication

16

cluster.query-threads

Threads per connected Axon Server node responsible for forwarding queries to that node.

1

cluster.command-threads

Threads per connected Axon Server node responsible for forwarding commands to that node.

1

grpc-buffered-messages

The initial flow control setting for gRPC level messages. This is the number of messages that may be en-route before the sender stops emitting messages. This setting is per-request and only affects streaming requests or responses. Application-level flow control settings and buffer restriction settings are still in effect.

500

default-command-timeout

Timeout (in ms.) for commands sent to command handler

300000

default-query-timeout

Timeout (in ms.) for queries sent to query handler

300000

query.timeout

Timeout for ad-hoc queries

300000

websocket-update.rate

Settings to influence how often Axon Server (in ms.) sends updates to the dashboard for updated metrics or tracking event processor status.

1000

websocket-update.initial-delay

On start, it will wait "initial-delay" (in ms.) before sending any updates. After that it will check every "rate" milliseconds.

10000

command-cache-capacity

Limits the total number of pending commands on an Axon Server node. If it is set to 0, the limit is determined dynamically based on the maximum memory available to the JVM.

0

query-cache-capacity

Limits the total number of pending queries on an Axon Server node. If it is set to 0, the limit is determined dynamically based on the maximum memory available to the JVM.

0

messages.context-buffer-limit

(Since 4.4.8) Limits the total number of pending commands or queries per context on an Axon Server node. If less than 0, there is no limit.

-1

query-handler-selector

(Since 4.4.10) Determines how Axon Server distributes queries over instances of the same application. By default, it will favor instances that give a faster response. Set to "round-robin" to distribute in a round robin way.

metrics

metrics-query-handler-selector.min-requests

(Since 4.4.10) Used in conjunction with the query-handler-selector set to "metric". Determines the minimum number of queries to be set to each instance of an application, before the router will distribute based on the metrics.

20

command-queue-capacity-per-client

Number of command requests for a specific command handling client that Axon Server will cache waiting for permits.

10000

query-queue-capacity-per-client

Number of query requests for a specific query handling client that Axon Server will cache waiting for permits.

10000

data-fetcher-threads

Number of threads that are allocated for doing longer running operations on the event store

24

data-writer-threads

Number of threads that are allocated for writing events to storage.

8

query-threads

Number of threads that are allocated for processing of external queries. Not to be confused with cluster.query-threads.

1

Recovery

recoveryfile

Start up with a recovery file to update node names in the controldb.

recovery.json

Plugins

plugins-enabled

enabled

true

plugin-package-directory

Directory where Axon Server stores the installed plugins. This directory must be writeable and persistent.

plugins/bundles

plugin-cache-directory

Cache directory fot the OSGi container. This directory must be writeable.

plugins/cache

plugin-clean-policy

Specifies if the OSGi container should clean up its cache directory on restart of the Axon Server node. Possible values are "none" and "onFirstInit".

onFirstInit

spring.servlet.multipart.max-file-size (no prefix)

Specifies the maximum size permitted for uploaded files.

10 MB

spring.servlet.multipart.max-request-size (no prefix)

Specifies the maximum size allowed for multipart/form-data requests.

10 MB