System Properties

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

• Configuration File

• Command Line

• Environment Variables

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 ...”, we can also supply individual configuration properties with “-Dproperty=value”

Environment Variable(s)

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	gRPC port for communication between Axon Server nodes within a cluster. (Axon EE only)	8224
	tags	Key/value pairs of tags for tag based connections for clients.	None
	devmode.enabled	Development mode which allows deleting all events from event store.(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. (e.g. 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. (e.g. 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. (e.g. logging.path = /var/log)	stdout
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	File containing the full certificate chain to be used in internal communication between Axon Server nodes. If not specified, Axon Server will use the primary key file from ssl.cert-chain-file. (Axon EE only)	None
	ssl.internal-trust-manager-file	Trusted certificates for verifying the other AxonServer's certificate. (Axon EE only)	None
	ssl.internal-private-key-file	File containing the private key to be used in internal communication between Axon Server nodes. If not specified, Axon Server will use the primary key file from ssl.private-key-file. (Axon EE only)	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	Token used to authenticate Axon Server instances in a cluster. (Axon EE only)
	accesscontrol.token	Token to be used by client applications connecting to Axon Server. (Axon SE only)
	accesscontrol.admin-token	Token to be used by CLI to manage Admin Server users. (Axon SE only)
	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.	16MB
	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 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	Option to disable plugin support. Plugin support is enabled by default.	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.	1MB
	spring.servlet.multipart.max-request-size (no prefix)	Specifies the maximum size allowed for multipart/form-data requests.	10MB