Configuration

This page describes all configuration options available for Axon Server Proxy.

Configuration file

Configuration is provided via a proxy.properties file placed in the working directory. Alternatively, any property can be set via environment variables (see Environment variables). Environment variables take precedence over values in proxy.properties.

There are no command-line property overrides. Configuration comes exclusively from proxy.properties or environment variables.

Required configuration

These configuration options must be specified for the proxy to function.

Axon Server nodes

proxy.servers

Comma-separated list of Axon Server admin node addresses. Each address can be in the format hostname or hostname:port. If no port is specified, the default port 8124 is used.

# Single server
proxy.servers=axonserver.local

# Single server with custom port
proxy.servers=axonserver.local:9124

# Multiple servers (HA setup)
proxy.servers=axonserver1.local:8124,axonserver2.local:8124,axonserver3.local:8124

# Multiple servers with mixed ports
proxy.servers=axonserver1.local:8124,axonserver2.local,axonserver3.local:9124
These should be the admin nodes of your Axon Server cluster, not regular nodes.

Proxy port

proxy.port

The TCP port on which the proxy listens for incoming gRPC connections from applications.

proxy.port=8124
Using the same port as Axon Server (8124) makes it easier for applications to switch between direct connection and proxy connection.

Basic configuration

Message size limits

proxy.maxMessageSize

Maximum message size that the proxy will accept and forward. Supports standard size formats (for example, 10MB, 512KB, 1GB). If not specified or set to 0, the gRPC default is used (no limit).

# Accept messages up to 10 megabytes
proxy.maxMessageSize=10MB

# Accept messages up to 512 kilobytes
proxy.maxMessageSize=512KB
This value cannot exceed 2 GB due to gRPC limitations.
Ensure this value is aligned with your Axon Server configuration and application requirements.

Disconnect timeout

proxy.disconnectTimeout

Number of seconds to wait for graceful shutdown of channels when closing connections. Specified as a plain integer. Default is 10.

# Default timeout
proxy.disconnectTimeout=10

# Longer timeout for graceful shutdown
proxy.disconnectTimeout=30

After this timeout, channels are forcibly closed if they haven’t terminated gracefully.

TLS configuration

The proxy supports TLS in two independently configurable contexts:

  1. Client-facing TLS: Secure connections from applications to the proxy

  2. Backend TLS: Secure connections from the proxy to Axon Server

TLS support exists so the proxy can operate in environments that require it, not as a primary reason to introduce the proxy. If your applications already connect directly to Axon Server with TLS, the proxy does not simplify that. The main benefit is when the two sides have different requirements. For example, applications in an external network requiring TLS, while the proxy and Axon Server share a trusted internal network where TLS is unnecessary.

Client-facing TLS (incoming)

Configure TLS for connections from applications to the proxy.

proxy.tlsEnabled

Enable TLS for incoming connections. Default is false.

proxy.tlsEnabled=true
proxy.tlsKey

Path to the private key file for TLS. Required when proxy.tlsEnabled=true.

proxy.tlsKey=/etc/axon-proxy/tls/server-key.pem

The file should be in PEM format.

proxy.tlsCert

Path to the certificate chain file for TLS. Required when proxy.tlsEnabled=true.

proxy.tlsCert=/etc/axon-proxy/tls/server-cert.pem

The file should contain the certificate and any intermediate CA certificates in PEM format.

Mutual TLS (client certificates)

In addition to serving its own certificate, the proxy can verify certificates presented by connecting applications (mutual TLS). This requires proxy.tlsEnabled=true.

proxy.tlsClientAuth

Whether applications must present a client certificate. Valid values:

  • NONE (default): Applications are not asked for a certificate

  • OPTIONAL: A certificate is requested; connections without one are still accepted, but a presented certificate must be valid

  • REQUIRE: Connections without a valid client certificate are rejected

    proxy.tlsClientAuth=REQUIRE
    REQUIRE applies to all applications connecting to the proxy at once. Use OPTIONAL during a migration phase to roll out client certificates gradually, then switch to REQUIRE. During such a migration, each incoming connection is logged with its transport security (PLAINTEXT, TLS, or mTLS), and the /connections endpoint reports it per connection, so you can verify that no application still connects without a client certificate before switching to REQUIRE.
    OPTIONAL does not guarantee that applications with untrusted certificates are rejected. A standard TLS client withholds a certificate that does not match the CAs the proxy advertises, and the connection is then accepted as if no certificate was configured. Only REQUIRE guarantees that every connected application holds a trusted certificate.
proxy.tlsTrustCerts

Path to a PEM file containing the CA certificates used to verify client certificates. Required when proxy.tlsClientAuth is OPTIONAL or REQUIRE.

proxy.tlsTrustCerts=/etc/axon-proxy/tls/trusted-clients.pem

The file is re-read every minute, so the set of trusted CA certificates can be rotated without restarting the proxy.

Complete client TLS example

proxy.tlsEnabled=true
proxy.tlsKey=/etc/axon-proxy/tls/server-key.pem
proxy.tlsCert=/etc/axon-proxy/tls/server-cert.pem

Complete mutual TLS example

proxy.tlsEnabled=true
proxy.tlsKey=/etc/axon-proxy/tls/server-key.pem
proxy.tlsCert=/etc/axon-proxy/tls/server-cert.pem
proxy.tlsClientAuth=REQUIRE
proxy.tlsTrustCerts=/etc/axon-proxy/tls/trusted-clients.pem

On the application side, configure the AxonServer Connector for Java with a client certificate using useMutualTransportSecurity:

AxonServerConnectionFactory.forClient("my-component")
        .routingServers(new ServerAddress("proxy.example.com", 8124))
        .useMutualTransportSecurity(new File("client-cert.pem"),
                                    new File("client-key.pem"),
                                    new File("proxy-ca.pem"))
        .build();

Backend TLS (outgoing)

Configure TLS for connections from the proxy to Axon Server.

proxy.internalTlsEnabled

Enable TLS for connections to Axon Server backend nodes. Default is false.

proxy.internalTlsEnabled=true
proxy.internalTrustCerts

Path to the file containing trusted CA certificates for backend connections. Required when proxy.internalTlsEnabled=true.

proxy.internalTrustCerts=/etc/axon-proxy/tls/ca-cert.pem

The file should contain one or more CA certificates in PEM format.

proxy.trustManagerVerification

Controls the level of certificate verification for backend connections. Valid values:

  • CERTIFICATE_AND_HOST_NAME_VERIFICATION (default): Full verification including hostname

  • CERTIFICATE_ONLY_VERIFICATION: Verify certificate validity but skip hostname check

  • INSECURELY_SKIP_ALL_VERIFICATION: Skip all verification (not recommended for production)

    # Default - full verification
proxy.trustManagerVerification=CERTIFICATE_AND_HOST_NAME_VERIFICATION

# Certificate only
proxy.trustManagerVerification=CERTIFICATE_ONLY_VERIFICATION

# Skip verification (development only!)
proxy.trustManagerVerification=INSECURELY_SKIP_ALL_VERIFICATION
    Using INSECURELY_SKIP_ALL_VERIFICATION disables all certificate validation and should only be used in development environments.

Complete backend TLS example

proxy.internalTlsEnabled=true
proxy.internalTrustCerts=/etc/axon-proxy/tls/ca-cert.pem
proxy.trustManagerVerification=CERTIFICATE_AND_HOST_NAME_VERIFICATION

Monitoring endpoint configuration

The proxy includes an HTTP monitoring endpoint that exposes health, metrics, and connection endpoints.

proxy.monitoring.enabled

Enable or disable the monitoring endpoint entirely. Default is true.

proxy.monitoring.enabled=false
proxy.monitoring.port

The port on which the monitoring HTTP endpoint listens. Default is 8080.

proxy.monitoring.port=9090
proxy.monitoring.host

The bind address for the monitoring HTTP endpoint. Default is 0.0.0.0 (all interfaces). Set to 127.0.0.1 to restrict access to the loopback interface only.

# Restrict to localhost only
proxy.monitoring.host=127.0.0.1

See Monitoring for details on the available monitoring endpoints.

Logging configuration

The proxy uses SLF4J with Logback for logging. Log levels and appenders are configured via a logback.xml file, not via proxy.properties.

The default configuration writes colorized, timestamped output to the console.

To override the logging configuration:

  • Place a logback.xml file in the working directory (it will be detected automatically at startup), or

  • Pass the path explicitly as a JVM system property:

    java -Dlogback.configurationFile=/etc/axon-proxy/logback.xml -jar axon-server-proxy.jar

Example logback.xml with file output and rolling policy:

<configuration>
  <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>/var/log/axon-proxy/proxy.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
      <fileNamePattern>/var/log/axon-proxy/proxy-%d{yyyy-MM-dd}.%i.log</fileNamePattern>
      <maxFileSize>100MB</maxFileSize>
      <maxHistory>10</maxHistory>
      <totalSizeCap>1GB</totalSizeCap>
    </rollingPolicy>
    <encoder>
      <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread] %logger{36} - %msg%n</pattern>
    </encoder>
  </appender>

  <root level="INFO">
    <appender-ref ref="FILE"/>
  </root>

  <logger name="io.axoniq.proxy" level="INFO"/>
</configuration>

Complete configuration examples

Minimal configuration

proxy.servers=axonserver.local:8124
proxy.port=8124

Production configuration (no TLS)

# Server configuration
proxy.servers=axonserver1:8124,axonserver2:8124,axonserver3:8124
proxy.port=8124

# Message size limit
proxy.maxMessageSize=10MB

# Disconnect timeout (seconds)
proxy.disconnectTimeout=30

# Monitoring endpoint
proxy.monitoring.port=8080
proxy.monitoring.host=127.0.0.1

Production configuration (full TLS)

# Server configuration
proxy.servers=axonserver1:8124,axonserver2:8124,axonserver3:8124
proxy.port=8124

# Message configuration
proxy.maxMessageSize=10MB
proxy.disconnectTimeout=30

# Client-facing TLS
proxy.tlsEnabled=true
proxy.tlsKey=/etc/axon-proxy/tls/server-key.pem
proxy.tlsCert=/etc/axon-proxy/tls/server-cert.pem

# Backend TLS
proxy.internalTlsEnabled=true
proxy.internalTrustCerts=/etc/axon-proxy/tls/ca-cert.pem
proxy.trustManagerVerification=CERTIFICATE_AND_HOST_NAME_VERIFICATION

# Monitoring endpoint
proxy.monitoring.port=8080
proxy.monitoring.host=127.0.0.1

Development configuration

# Server configuration
proxy.servers=localhost:8124
proxy.port=8125

# Monitoring endpoint on default port
proxy.monitoring.port=8080

Environment variables

All configuration properties can also be set via environment variables. Environment variables take precedence over values in proxy.properties.

The naming rule is: replace dots with underscores, insert an underscore before each uppercase letter in camelCase names, and uppercase the entire result.

For example: proxy.tlsEnabled becomes PROXY_TLS_ENABLED.

Property Environment variable

proxy.servers

PROXY_SERVERS

proxy.port

PROXY_PORT

proxy.maxMessageSize

PROXY_MAX_MESSAGE_SIZE

proxy.disconnectTimeout

PROXY_DISCONNECT_TIMEOUT

proxy.tlsEnabled

PROXY_TLS_ENABLED

proxy.tlsKey

PROXY_TLS_KEY

proxy.tlsCert

PROXY_TLS_CERT

proxy.tlsClientAuth

PROXY_TLS_CLIENT_AUTH

proxy.tlsTrustCerts

PROXY_TLS_TRUST_CERTS

proxy.internalTlsEnabled

PROXY_INTERNAL_TLS_ENABLED

proxy.internalTrustCerts

PROXY_INTERNAL_TRUST_CERTS

proxy.trustManagerVerification

PROXY_TRUST_MANAGER_VERIFICATION

proxy.monitoring.enabled

PROXY_MANAGEMENT_ENABLED

proxy.monitoring.port

PROXY_MANAGEMENT_PORT

proxy.monitoring.host

PROXY_MANAGEMENT_HOST

Example:

export PROXY_SERVERS=axonserver1:8124,axonserver2:8124
export PROXY_PORT=8124
export PROXY_TLS_ENABLED=true

Configuration validation

The proxy validates configuration on startup and will fail to start if:

  • proxy.servers is not specified or empty

  • proxy.port is not specified

  • proxy.tlsEnabled=true but proxy.tlsKey or proxy.tlsCert is missing

  • proxy.tlsClientAuth is OPTIONAL or REQUIRE but proxy.tlsEnabled is false

  • proxy.tlsClientAuth is OPTIONAL or REQUIRE but proxy.tlsTrustCerts is missing

  • proxy.internalTlsEnabled=true but proxy.internalTrustCerts is missing

  • proxy.maxMessageSize exceeds 2 GB

  • proxy.disconnectTimeout is negative

Next steps