Configurations
Overview
This page describes different configurations available for Java KeySquare API and server components.
The easiest way to set configurations is by using Environment Variables.
KeySquare server components log all environment variables on start-up, e.g.
2025-07-29 21:20:17,230 INFO [main] t.k.a.m.Main [Main.java:92] KS_APP_KEY_ACCESS_URL .................... http://localhost:6800
Similary, KeySquare java API logs the configuration used to create KeySession on intialization, e.g.
2025-07-29 21:20:19,541 INFO [main] t.k.i.a.AbstractKeySession [AbstractKeySession.java:125] Context: KeySessionContext [applicationName=key-access, cpus=null
note
All configuration changes are applied on startup and a running instance must be restarted in order for configuration changes to take effect.
Common Configuration (Impacts multiple apps)
Licensing
| Property | Default | Description |
|---|---|---|
| KS_LICENCE | KeySquare license key required for platform operation |
Ingress/Load Balancer
| Property | Default | Description |
|---|---|---|
| KS_INGRESS_HOST | ${HOSTNAME} | Ingress hostname (defaults to system hostname) |
| KS_INGRESS_HTTP_PORT | 6500 | Ingress HTTP port for routing requests |
| KS_INGRESS_STATS_HTTP_PORT | 6502 | Ingress statistics and monitoring port |
Service Configuration
| Property | Default | Description |
|---|---|---|
| KS_KEY_UI_HOST | 0.0.0.0 | Host binding for Key UI application |
| KS_KEY_UI_HTTP_PORT | 6600 | HTTP port for Key UI application |
| KS_KEY_ACCESS_HOST | localhost | Host for Key Access service |
| KS_KEY_ACCESS_HTTP_PORT | 6800 | HTTP port for KeyAccess service |
| KS_WEB_DATA_SERVER_HOST | localhost | Host for WebDataServer |
| KS_WEB_DATA_SERVER_HTTP_PORT | 6900 | HTTP port for WebDataServer |
| KS_KEY_SQUARE_PROXY_GRPC_HOST | <auto> | Host for KeySquare Proxy gRPC service - auto resolves to KeyAccess FQN |
| KS_KEY_SQUARE_PROXY_GRPC_PORT | 6700 | gRPC port for KeySquare Proxy service |
QuestDB Configuration
| Property | Default | Description |
|---|---|---|
| KS_QUESTDB_HOST | localhost | QuestDB server hostname |
| KS_QUESTDB_HTTP_PORT | 5510 | QuestDB HTTP API port |
| KS_QUESTDB_HTTP_USER | admin | QuestDB HTTP API username |
| KS_QUESTDB_HTTP_PASSWORD | ksquest | QuestDB HTTP API password |
| KS_QUESTDB_PG_PORT | 5512 | QuestDB PostgreSQL wire protocol port |
| KS_QUESTDB_MONITOR_PORT | 5514 | QuestDB monitoring port |
| KS_QUESTDB_PG_USER | admin | QuestDB PostgreSQL username |
| KS_QUESTDB_PG_PASSWORD | ksquest | QuestDB PostgreSQL password |
Database Connectivity
| Property | Default | Description |
|---|---|---|
| KS_QUESTDB_URL | <auto> | Complete QuestDB connection URL with parameters |
| datasource.driverClassName | org.postgresql.Driver | JDBC driver class for database connections |
| datasource.url | jdbc:postgresql://${KS_QUESTDB_HOST}:${KS_QUESTDB_PG_PORT}/qdb | JDBC URL for database connections |
| datasource.username | ${KS_QUESTDB_PG_USER} | Database username |
| datasource.password | ${KS_QUESTDB_PG_PASSWORD} | Database password |
Grafana Configuration
| Property | Default | Description |
|---|---|---|
| KS_GRAFANA_HOST | localhost | Grafana server hostname |
| KS_GRAFANA_HTTP_PORT | 5500 | Grafana HTTP port |
| KS_GRAFANA_ADMIN_PASSWORD | admin | Grafana admin user password |
KeySession (KeySquare Java API)
Refer to KeySessionContext for most up to date list of properties and their description.
Application
| Property | Default | Description |
|---|---|---|
| APP_NAME | This is the application name to use to connect to KeySquare. This app name must be pre-registered in KeyAccess and permissioned to access relevant data | |
| APP_CPUS | null | Defines the cpu(s) available to pin application threads |
| KS_APP_API_KEY | The api key to use when registering application on start up | |
| KS_APP_APPLICATION_IDLE_STRATEGY | SleepingMillisIdleStrategy | The idle strategy to use for the application thread when it has no messages to process |
| KS_APP_CONCURRENCY_MODE | CONCURRENT | Defines the concurrency mode of the application - when more than one thread will be interacting with the session the CONCURRENT mode should be used. The EXCLUSIVE mode provides better performance and can be used when all interactions with the session are made using the "ks" thread provided by the session. |
| KS_APP_SESSION_THREAD_NAME | "ks" | Defines the thread name to use by the session |
| KS_APP_EDIT_API_SUPPORTED | true | Can be used to disable the Edit API - this can provide slightly improved performance in certain cases |
| KS_APP_SHUTDOWN_HOOK_ENABLED | true | Can be used to disable the shutdown hook that gets automatically registered by the session |
| KS_APP_AUTO_RECONNECT | true | Can be used to prevent automatic reconnection of the session following a disconnect |
| KS_APP_AUTO_RECONNECT_APPLY_SUBSCRIPTIONS | true | Can be used to prevent the automatic application of subscriptions when an application is reconnected following a disconnect |
| KS_APP_AUTO_RECONNECT_REPUBLISH | true | Can be used to prevent the automatic republication of data when an application is reconnected following a disconnect |
| KS_APP_EXPERIMENTAL_FLAGS | Comma-separated list of experimental feature flags | |
| KS_IR_REPLACE_SAME_VERSION | false | For subscribers, whether to replace local schema definition if the new schema has the same version - useful for development. Only applicable if explicitly subscribed to Schema |
Transport
| Property | Default | Description |
|---|---|---|
| KS_APP_TRANSPORT_MODE | IPC_UDP | The transport mode to use, e.g. IPC_UDP or TCP |
| KS_APP_TRANSPORT_EVENT_LIMIT | 1000 | Defines the batch size of events being processed |
| aeron.dir | The location of the aeron directory to use when in IPC_UDP mode | |
| KS_APP_TRANSPORT_IPC_UDP_INTERFACE | Config.AUTO | The network interface to use when in IPC_UDP mode |
| KS_APP_TRANSPORT_TCP_BUFFER_SIZE | 67108864 (64MB) | The TCP buffer size when operating in TCP mode |
Monitoring
| Property | Default | Description |
|---|---|---|
| KS_APP_MONITORING_HEALTH_DIRECTORY | null | Defines the health directory in which to write a health file once an application submits a LifeCycle Status of Online |
| KS_APP_MONITORING_BUFFER_SIZE | 67108864 (64MB) | The monitoring buffer size |
| KS_APP_MONITORING_IDLE_STRATEGY | SleepingMillisIdleStrategy | The monitoring thread idle strategy |
| KS_APP_MONITORING_HEARTBEAT_INTERVAL_MILLIS | 1000 | The heartbeat interval in milliseconds |
| KS_APP_MONITORING_HEARTBEAT_TIMEOUT_MILLIS | 5000 | The heartbeat timeout in milliseconds |
KeyAccess
| Property | Default | Description |
|---|---|---|
| KS_APP_KEY_ACCESS_URL | The URL location of the Key Access application used for application registration |
Aeron Media Driver
| Property | Default | Description |
|---|---|---|
| aeron.dir | /dev/shm/aeron-ks | Aeron media driver directory location |
| aeron.spies.simulate.connection | true | Enable Aeron spy connection simulation |
| aeron.threading.mode | DEDICATED | Aeron threading mode (SHARED, SHARED_NETWORK, DEDICATED) |
| aeron.media.conductorIdleStrategy | org.agrona.concurrent.BusySpinIdleStrategy | Idle strategy for Aeron conductor thread |
| aeron.media.receiverIdleStrategy | org.agrona.concurrent.NoOpIdleStrategy | Idle strategy for Aeron receiver thread |
| aeron.media.senderIdleStrategy | org.agrona.concurrent.NoOpIdleStrategy | Idle strategy for Aeron sender thread |
KeyAccess
| Property | Default | Description |
|---|---|---|
| KS_KEY_ACCESS_HOST | localhost | Host for Key Access service |
| KS_KEY_ACCESS_HTTP_PORT | 6800 | HTTP port for KeyAccess service |
| KS_APP_KEY_ACCESS_SERVICE_KEY | ksadmin | Service key - Clients must provide this key to register or make entitlement changes |
| KS_KEY_ACCESS_REGISTRATION_TIMEOUT_SECONDS | 10 | Number of seconds an application is considered 'registered' without heartbeats |
Sequencer
| Property | Default | Description |
|---|---|---|
| KS_SEQUENCER_INPUT_CHANNEL | aeron-spy:aeron:udp?endpoint=224.0.0.1:4096|ttl=8 | Aeron channel for sequencer input stream |
| KS_SEQUENCER_INPUT_STREAM_ID | 1 | Stream ID for sequencer input |
| KS_SEQUENCER_OUTPUT_CHANNEL | aeron-spy:aeron:udp?endpoint=224.0.0.3:4096|ttl=8 | Aeron channel for sequencer output stream |
| KS_SEQUENCER_OUTPUT_STREAM_ID | 3 | Stream ID for sequencer output |
Relay Live
Common configuration only
Relay Cache
| Property | Default | Description |
|---|---|---|
| RELAY_CACHE_MESSAGE_BATCH_SIZE | 10_000 | Number of events relay-cache sends to a subscriber per batch. Batching allows consumers to 'catch-up' and gives relay opportunity to service other clients |
KeySquare Proxy
| Property | Default | Description |
|---|---|---|
| KS_KEY_SQUARE_PROXY_GRPC_PORT | 6700 | gRPC port for KeySquare Proxy service |
| KS_KEY_SQUARE_PROXY_EVENT_LIMIT | 1000 | Event processing batch limit for KeySquare Proxy |
WebDataServer
| Property | Default | Description |
|---|---|---|
| KS_WEBSOCKET_MESSAGES_PER_SECONDS | 2 | Number of unique events to send over web socket for a given topic |
| KS_APP_KEY_ACCESS_SERVICE_KEY | ksadmin | Used to proxy requests on behalf of users with role = ADMIN |
| KS_KEY_ACCESS_TOPIC_SOURCE | key-access | Topic Source to use when subscribing to live permissions from KeyAccess |
| KS_WEB_DATA_SERVER_ADMIN_PASSWORD | ksadmin | Admin password for Web Data Server |
| KS_APP_WEB_DATA_SERVER_SECURITY | Security authentication method for WebDataServer | |
| KS_APP_WEB_DATA_SERVER_LDAP_URL | LDAP server URL for authentication | |
| KS_APP_WEB_DATA_SERVER_LDAP_USER_SEARCH_FILTER | LDAP search filter for user authentication | |
| KS_APP_WEB_DATA_SERVER_LDAP_USER_SEARCH_BASE | LDAP base DN for user searches |
See Authentication for more details on the WebDataServer security settings
Key UI
Key UI needs to connect to WebDataServer to receive data. Key UI and WebDataServer should be run on the same server
| Property | Default | Description |
|---|---|---|
| KS_WEB_DATA_SERVER_HOST | localhost | Host for WebDataServer |
| KS_WEB_DATA_SERVER_HTTP_PORT | 6900 | HTTP port for WebDataServer |