MaxScale Configuration Settings

Browse the comprehensive list of MariaDB MaxScale configuration parameters. This reference details valid values, default settings, and dynamic capabilities for servers, services, and monitors.

General

MaxScale

Filter

module

• Type: filter

• Mandatory: Yes

• Dynamic: No

• Description: The module parameter specifies the name of the filter module that is included in the routing chain.

Global Settings

admin_audit

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Enables the logging of incoming REST API requests for auditing and monitoring purposes.

admin_audit_exclude_methods

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: GET, PUT, POST, PATCH, DELETE, HEAD, OPTIONS, CONNECT, TRACE

• Default: No exclusions

• Description: Provides a list of HTTP methods to be excluded from REST API audit logging, separated by commas.

admin_audit_file

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: /var/log/maxscale/admin_audit.csv

• Description: Defines the location of the REST API audit logs.

admin_auth

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: true

• Description: Allows HTTP Basic authentication for the REST API.

admin_enabled

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: true

• Description: Enables or disables the MaxScale admin interface.

admin_gui

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: true

• Description: Enables or disables the graphical user interface (GUI) for the admin interface.

admin_host

• Type: string

• Mandatory: No

• Dynamic: No

• Default: "127.0.0.1"

• Description: Provides the network interface address that the REST API is listening to.

admin_jwt_algorithm

• Type: enum

• Mandatory: No

• Dynamic: No

• Values: auto, HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, ED25519, ED448

• Default: auto

• Description: Specifies the algorithm for signing JSON Web Tokens (JWTs) for the REST API.

admin_jwt_issuer

• Type: string

• Mandatory: No

• Dynamic: No

• Default: maxscale

• Description: Specifies the issuer ("iss") claim in the REST API-generated JSON Web Tokens.

admin_jwt_key

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Identifies the encryption key that is used to sign JSON Web Tokens.

admin_jwt_max_age

• Type: duration

• Mandatory: No

• Dynamic: No

• Default: 24h

• Description: Specifies the maximum duration of JWTs issued by the REST API.

admin_log_auth_failures

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Enables logging of authentication failures for the admin interface.

admin_oidc_client_id

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Specifies the client ID for OpenID Connect (OIDC) login authentication requests.

admin_oidc_client_secret

• Type: password

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Specifies the client secret used for OIDC authentication requests.

admin_oidc_extra_options

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Defines additional parameters that should be included in authorization requests for OIDC.

admin_oidc_flow

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: auto, implicit, code

• Default: auto

• Description: Describes the OIDC authentication flow used for SSO.

admin_oidc_ssl_insecure

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Disables TLS certificate validation while retrieving OIDC certificates.

admin_oidc_url

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Specifies the OIDC provider's URL, which is needed to validate JWT.

admin_pam_readonly_service

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Defines the PAM service that is used to verify read-only REST API users.

admin_pam_readwrite_service

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Specifies the PAM service used for authentication REST API users with read and write access.

admin_port

• Type: number

• Mandatory: No

• Dynamic: No

• Default: 8989

• Description: Defines the port at which the REST API waits for incoming connections.

admin_readwrite_hosts

• Type: string

• Mandatory: No

• Dynamic: No

• Default: %

• Description: Hosts can perform any REST API operation with read and write access.

admin_secure_gui

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: true

• Description: Manages whether the GUI are accessible only over secure HTTPS.

admin_ssl_ca

• Type: path

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Path to the CA sertificate for outgoing HTTPS requests.

admin_ssl_cert

• Type: path

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Provides the path of the TLS public certificate in PEM format used by the REST API.

admin_ssl_cipher

• Type: string

• Mandatory: No

• Dynamic: No

• Description: Defines additional TLS cipher configuration for the REST API.

admin_ssl_key

• Type: path

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Indicates the location of the TLS private key in PEM format that the admin interface uses.

admin_ssl_passphrase

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Provides the passphrase needed to decrypt the admin interface's TLS private key.

admin_ssl_version

• Type: enum_mask

• Mandatory: No

• Dynamic: No

• Values: MAX, TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3, TLSv10, TLSv11, TLSv12, TLSv13

• Default: MAX

• Description: Specifies the allowed TLS protocol versions for the REST API.

admin_verify_url

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Delegate the validation of tokens to an external server.

allow_duplicate_servers

• Type: boolean

• Default: false

• Description: Allows multiple server definitions to use the same IP address and port combination.

auth_connect_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 10s

• Description: Sets the connection timeout for retrieving user authentication data from backend servers.

auto_tune

• Type: string list

• Values: all or list of auto tunable parameters, separated by ,

• Default: No

• Mandatory: No

• Dynamic: No

• Description: Allows automatic tuning of specified configuration parameters based on backend server values.

config_sync_cluster

• Type: monitor

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Monitor name used for configuration synchronization

config_sync_db

• Type: string

• Mandatory: No

• Dynamic: No

• Default: mysql

• Description: Identifies the database that contains the maxscale_config table, which is used to synchronize configurations.

config_sync_interval

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 5s

• Description: Specifies how often MaxScale synchronizes configuration changes with the cluster.

config_sync_password

• Type: password

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description:

config_sync_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 10s

• Description: Timeout for config sync SQL operations.

config_sync_user

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Username used for configuration sync database access across MaxScale instances.

connector_plugindir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: OS Dependent

• Description: Specifies the ditrectory that contains MaxScale's MariaDB Connector-C authentication plugins.

core_file

• Type: boolean

• Default: false

• Dynamic: No

• Description: Specifies whether a core dump file is generated in the event that MaxScale crashes.

cors_allow_origin

• Type: string

• Default: N/A

• Description: Enables CORS and sets the Access-Control-Allow-Origin header to the specified value.

datadir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: /var/lib/maxscale

• Description: Specifies the location of MaxScale's data files directory.

debug

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Defines debug options equivalent to the --debug command line argument.

disable_fcrdns

• Type: boolean

• Default: false

• Description: Disables Forward-Confirmed Reverse DNS (fcRDNS) lookups for client connections.

disable_module_unloading

• Type: boolean

• Default: false

• Description: Disables the unloading of modules at exit. This provides more accurate Valgrind leak reports when memory is allocated within shared libraries.

disable_statement_logging

• Type: boolean

• Default: true

• Description: Disables the logging of SQL statements sent by MaxScale to backend servers.

dump_last_statements

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: on_close, on_error, never

• Default: never

• Description: Manages when MaxScale logs the last statements executed by a client session.

dump_network_traffic

• Type: boolean

• Default: false

• Description: Dumps all raw network traffic to the log as info level messages.

enable_cors

• Type: boolean

• Default: false

• Description: Enables Cross-Origin Resource Sharing (CORS) support for the MaxScale REST API.

enable_module_unloading

• Type: boolean

• Default: true

• Description: Re-enables module unloading at exit (overrides disable-module-unloading)

enable_statement_logging

• Type: boolean

• Default: false

• Description: Enables logging of all SQL statements sent by MaxScale monitors and authenticators to the backend servers.

exception_frequency

• Type: integer

• Default: true

• Description: Defines the frequency of generated API exceptions.

gdb_stacktrace

• Type: boolean

• Default: true

• Description: When enabled, MaxScale attempts to use GDB to generate detailed stack traces during a crash. Can be disabled with gdb-stacktrace=false.

host_cache_size

• Type: integer

• Default: 128

• Dynamic: Yes

• Description: Sets the number of entries in the reverse DNS lookup cache for client hostnames.

key_manager

• Type: enum

• Dynamic: Yes

• Values: none, file, kmip, vault

• Default: none

• Description: Defines the encrytion key manager that MaxScale uses.

libdir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: OS Dependent

• Description: Specifies the directory that MaxScale uses to locate modules.

load_persisted_configs

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: true

• Description: Loads saved runtime changes at startup.

local_address

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Defines what specific local interface to use when connecting to servers.

log_augmentation

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 0

• Description: Includes function names to logged messages.

log_debug

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Log debug messages when enabled.

log_info

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Log detailed info messages when enabled.

log_notice

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Log notice level messages when enabled.

log_throttling

• Type: number, duration, duration

• Mandatory: No

• Dynamic: Yes

• Default: 10, 1000ms, 10000ms

• Description: Manages how frequently repeated errors or warnings are logged.

log_warn_super_user

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: false

• Description: Log warning when a client with SUPER privilege connects.

log_warning

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Enable service-level warning logging.

logdir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: /var/log/maxscale

• Description: Defines the directory where log files are stored.

max_auth_errors_until_block

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 10

• Description: Maximum number of authentication failures before temprarily blocking a host.

maxlog

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Enables logging of messages to the MaxScale log file.

module_configdir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: /etc/maxscale.modules.d/

• Description: Directory for module-specific configuration files.

ms_timestamp

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Adds millisecond precision to logfile timestamps.

passive

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Deprecated - use cooperative monitoring instead.

persist_runtime_changes

• Type: boolean

• Default: true

• Dynamic: No

• Description: Save runtime configuration changes to disk.

persistdir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: /var/lib/maxscale/maxscale.cnf.d/

• Description: Directory where runtime configuration changes are stored.

piddir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: /run/maxscale

• Description: Specifies the directory containing the MaxScale process ID (PID) file.

query_classifier_cache_size

• Type: size

• Mandatory: No

• Dynamic: Yes

• Default: System Dependent

• Description: Sets the maximum size of the query classifier cache.

query_retries

• Type: number

• Mandatory: No

• Dynamic: No

• Default: 1

• Description: Deprecated and ignored.

query_retry_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 10s

• Description: Deprecated and ignored.

rebalance_period

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 0s

• Description: Defines the interval for monitoring and rebalancing worker thread load. A value of 0 disables this function.

rebalance_threshold

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 20

• Description: Load difference percentage that triggers thread rebalancing.

rebalance_window

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 10

• Description: Manages how many seconds of load to consider for rebalancing.

redirect_output_to_file

• Type: boolean

• Default: false

• Description: Redirects stdout and stderr to the specified file path.

require_secure_transport

• Type: boolean

• Default: false

• Dynamic: No

• Description: Requires SSL for all listeners, servers, and the REST API.

retain_last_statements

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 0

• Description: Specifies how many statements MaxScale can store per session.

secretsdir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Location of the .secrets file for password encryption.

session_trace

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 0

• Description: Defines how many log entries are stored in the session trace log.

session_trace_match

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Specifies a refular expression pattern used to filter session trace logs.

sharedir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: /usr/share/maxscale

• Description: Defines the directory where static data assests are loaded.

skip_name_resolve

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Disables reverse DNS lookups of client IP addresses.

sql_mode

• Type: enum

• Mandatory: No

• Dynamic: No

• Values: default, oracle

• Default: default

• Description: Defines which SQL language mode the query classifier should expect.

sql_batch_size

• Type: size

• Default: 10MiB

• Description: Sets the maximum batch size for REST API SQL statement processing.

substitute_variables

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: false

• Description: Allows use of environment variables within MaxScale configuration files.

syslog

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Writes log messages to the system journal via the system logging interface.

telemetry

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Enables sending metrics to OpenTelemetry Collector.

telemetry_attributes

• Type: stringlist

• Default: empty

• Dynamic: Yes

• Mandatory: No

• Description: Global attributes to send with every metric.

telemetry_ssl_ca

• Type: path

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Path to trusted CA certificate (PEM) used for validating TLS connections in telemetry.

telemetry_ssl_cert

• Type: path

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Specifies the file path to the TLS public certificate in PEM format for telemetry.

telemetry_ssl_insecure

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Disable TLS certificate validation for telemetry.

telemetry_ssl_key

• Type: path

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: TLS private key for encrypted telemetry.

telemetry_update_interval

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 60s

• Description: Defines the minimum interval between sending metrics to the telemetry collector.

telemetry_url

• Type: string

• Mandatory: No

• Dynamic: No

• Default: http://localhost:4318/v1/metrics

• Description: Defines the OpenTelemetry endpoint where MaxScale pushes metrics.

threads

• Type: number or auto

• Mandatory: No

• Dynamic: No

• Default: auto

• Description: Manages the number of worker threads for routing client traffic.

threads_max

• Type: positive integer

• Default: 256

• Dynamic: No

• Description: Hard limit for the number of worker threads.

trace_file_dir

• Type: path

• Mandatory: No

• Dynamic: No

• Description: Directory for low-overhead trace log files.

trace_file_size

• Type: size

• Mandatory: No

• Dynamic: Yes

• Description: Amount of log data to keep in trace files.

users_refresh_interval

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 0s

• Description: Defines the interval for automatically refreshing user accounts from backend servers.

users_refresh_time

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 30s

• Description: Maximum frequency for refreshing user accounts from backend servers after authentication failures.

writeq_high_water

• Type: size

• Mandatory: No

• Dynamic: Yes

• Default: 65536

• Description: High water mark for network write buffer throttling.

writeq_low_water

• Type: size

• Mandatory: No

• Dynamic: Yes

• Default: 1024

• Description: Low water mark to disable network write throttling.

Service

auth_all_servers

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Manages whether authentication data is loaded from one server or aggregated from all servers.

cluster

• Type: monitor

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Monitor that defines servers for this service.

connection_keepalive

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 300s

• Auto tune: Yes

• Description: Send pings to keep idle backend connections alive.

disable_sescmd_history

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Disable session command history entirely.

enable_root_user

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Controls whether the root user is allowed to connect through MaxScale to backend servers.

filters

• Type: filter list

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Defines a list of filters applied to client requests before routing to backend servers.

force_connection_keepalive

• Type: boolean

• Mandatory No

• Dynamic: Yes

• Default: false

• Description: Send keepalive pings to any backends even when client is idle.

idle_session_pool_time

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: -1s

• Description: Time idle before pooling backend connections.

log_auth_warnings

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Log authentication failures and warnings.

log_debug

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Enable service-level debug logging.

log_info

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Enable service-level info logging.

log_notice

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Enable service-level notice logging.

log_warning

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Enable service-level warning logging.

max_connections

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 0 in MaxScale, 15 in MaxScale Trial.

• Minimum: 0 in MaxScale, 1 in MaxScale Trial.

• Maximum: Unlimited in MaxScale, 15 in MaxScale Trial.

• Description: Maximum number of simultaneous connections allowed to this service.

max_sescmd_history

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 50

• Description: Maximum session commands to store for replay.

multiplex_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 60s

• Description: Maximum wait time for backend connection.

net_write_timeout

• Type: durations

• Mandatory No

• Dynamic: Yes

• Default: 0s

• Description: Disconnects connection if data buffered longer than this duration.

password

• Type: string

• Mandatory: Yes

• Dynamic: Yes

• Description: Specifies the password the service uses to retrieve user accounts from backends.

prune_sescmd_history

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Prune old session commands when limit exceeded the configured value.

retain_last_statements

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: -1

• Description: Defines the number of statements MaxScale stores per session.

role

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Role to activate after connecting to a server.

router

• Type: router

• Mandatory: Yes

• Dynamic: No

• Description: Defines the router module that a service uses to direct client connections to backend servers.

servers

• Type: server list

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Specifies the backend servers associated with the service.

session_track_trx_state

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Improves accuracy by enabling backend-based transaction state tracking.

strip_db_esc

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Remove escape characters from database names when loading users grants from a backend server.

targets

• Type: target list

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Nested services or servers for multi-level routing.

user

• Type: string

• Mandatory: Yes

• Dynamic: Yes

• Description: Username for retrieving user account information from backends.

user_accounts_file

• Type: path

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Specifies the path to a JSON file containing additional user accounts for client authentication.

user_accounts_file_usage

• Type: enum

• Mandatory: No

• Dynamic: No

• Values: add_when_load_ok, file_only_always

• Default: add_when_load_ok

• Description: Specifies when the user accounts file is read instead of or alongside server data.

version_string

• Type: string

• Mandatory: No

• Dynamic: No

• Default: None

• Description: Custom version string sent in MySQL handshake.

wait_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 28800s (>= MaxScale 24.02.5, 25.01.2), 0s (<= MaxScale 24.02.4, 25.01.1)

• Auto tune: Yes

• Description: Specifies the idle timeout for client sessions before termination.

Settings for File-based Key Manager

file.keyfile

• Type: path

• Mandatory: Yes

• Dynamic: Yes

• Description: Path to file containing encryption keys.

Settings for HashiCorp Vault Key Manager

vault.ca

• Type: path

• Default: ""

• Dynamic: Yes

• Description: Defines the CA certificate used for validating Vault server connections.

vault.host

• Type: string

• Default: localhost

• Dynamic: Yes

• Description: Specifies the hostname of the Vault server.

vault.mount

• Type: string

• Default: secret

• Dynamic: Yes

• Description: Provides the Key-Value mount path in Vault where secrets are stored.

vault.port

• Type: integer

• Default: 8200

• Dynamic: Yes

• Description: Defines the port on which the Vault server listens.

vault.timeout

• Type: duration

• Default: 30s

• Dynamic: Yes

• Description: Sets the timeout for requests and connections to the Vault server.

vault.tls

• Type: boolean

• Default: true

• Dynamic: Yes

• Description: Manages whether encrypted (HTTPS) or unencrypted (HTTP) connections are used when communicating with the Vault server.

vault.token

• Type: password

• Mandatory: Yes

• Dynamic: Yes

• Description: Provides the authentication token to access the Vault server.

Settings for KMIP Key Manager

kmip.ca

• Type: path

• Default: ""

• Dynamic: Yes

• Description: CA ceritficate for KMIP server.

kmip.cert

• Type: path

• Mandatory: Yes

• Dynamic: Yes

• Description: Client certificate for KMIP authentication.

kmip.host

• Type: string

• Mandatory: Yes

• Dynamic: Yes

kmip.key

• Type: path

• Mandatory: Yes

• Dynamic: Yes

• Description: Specifies the client private key used for connecting to the KMIP server.

kmip.port

• Type: integer

• Mandatory: Yes

• Dynamic: Yes

• Description: Defines the port on which the KMIP server listens.

Settings for TLS/SSL Encryption

ssl

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Enables SSL encryption for connections when set to true.

ssl_ca

• Type: path

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Specifies the CA certificate used to validate the peer’s certificate.

ssl_cert

• Type: path

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Deprecated - use ssl_ca instead.

ssl_cert_verify_depth

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 9

• Description: Specifies the maximum depth of the CA chain during verification.

ssl_cipher

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Provides the list of TLS ciphers to use for SSL connections.

ssl_crl

• Type: path

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Specifies the CRL file used to validate revoked SSL certificates.

ssl_key

• Type: path

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Specifies the path to the SSL/TLS private key that is used for secure connections.

ssl_passphrase

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Defines the passphrase used to decrypt the SSL/TLS private key.

ssl_verify_peer_certificate

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Verifies the peer's SSL/TLS certificate against a trusted CA.

ssl_verify_peer_host

• Type: boolean

• Mandatory No

• Dynamic: Yes

• Default: false

• Description: Verifies the peer's hostname or IP address using its SSL/TLS certificate.

ssl_version

• Type: enum_mask

• Mandatory: No

• Dynamic: No

• Values: MAX, TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3, TLSv10, TLSv11, TLSv12, TLSv13

• Default: MAX

• Description: Lists the TLS protocol versions that are allowed for SSL/TLS connections.

reference

maxscale-listeners

Settings

address

• Type: string

• Mandatory: No

• Dynamic: No

• Default: "::"

• Description: Indicates the hostname or address that the listener binds to when a connection is made.

authenticator

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Specifies the authenticator module used for client authentication.

authenticator_options

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Provides additional configuration settings for the authenticator module.

connection_init_sql_file

• Type: path

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Specifies a file containing SQL statements executed on backend connections after authentication.

connection_metadata

• Type: stringlist

• Default: character_set_client=auto,character_set_connection=auto,character_set_results=auto,max_allowed_packet=auto,system_time_zone=auto,time_zone=auto,tx_isolation=auto,maxscale=auto

• Dynamic: Yes

• Mandatory: No

• Description: Provides the metadata that is given to clients upon connection as a list of key-value pairs separated by commas.

port

• Type: number

• Mandatory: Yes, if socket is not provided.

• Dynamic: No

• Default: 0

• Description: Specifies the port on which the listener accepts connections.

protocol

• Type: protocol

• Mandatory: No

• Dynamic: No

• Default: mariadb

• Description: Defines the protocol module that clients and MaxScale use to communicate.

redirect_url

• Type: URL

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Specifies the database URL that clients are sent to following authentication.

service

• Type: service

• Mandatory: Yes

• Dynamic: No

• Description: Identifies the service that the listener is connected to.

socket

• Type: string

• Mandatory: Yes, if port is not provided.

• Dynamic: No

• Default: ""

• Description: Defines the Unix domain socket that the listener uses to receive inbound connections.

sql_mode

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: default, oracle

• Default: default

• Description: Specifies the listener's SQL mode, overriding the global sql_mode setting if it is set.

user_mapping_file

• Type: path

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Provides optional backend credentials for MariaDB protocol connections, as well as a JSON file that specifies user and group mappings.

maxscale-servers

Settings

address

• Type: string

• Mandatory: Yes, if socket is not provided.

• Dynamic: Yes

• Default: ""

• Description: Specifies the hostname or IP address of the backend server to which MaxScale connects.

disk_space_threshold

• Type: Custom

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Defines disk usage threshold that triggers warnings or actions when exceeded.

extra_port

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 0

• Description: Specifies an alternative port that MaxScale uses for administrative connections to the backend server.

initial_status

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: down, up, read, write

• Default: down

• Description: Provides the initial status of the server when it starts or its reconfigured.

labels

• Type: string list

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Specifies a comma-separated list of user-defined labels assigned to the server.

max_routing_connections

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 0 in MaxScale, 15 in MaxScale Trial.

• Minimum: 0 in MaxScale, 1 in MaxScale Trial.

• Maximum: Unlimited in MaxScale, 15 in MaxScale Trial.

• Description: Provides the maximum number of routing connections to the server.

monitorpw

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Specifies the password that is needed to authenticate server-specific monitoring.

monitoruser

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Specifies the username used for authentication in server‑specific monitoring.

persistmaxtime

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 0s

• Description: Shows how long a connection can stay in the persistent pool before being discarded.

persistpoolmax

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 0

• Description: Defines the server connection pool's maximum size.

port

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 3306

• Description: Identifies the port that connections are accepted by the backend server.

priority

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 0

• Description: Sets the server's priority for selecting the main node.

private_address

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: An alternate hostname or IP address is used for internal communications.

proxy_protocol

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Allows the original client IP address and port to be forwarded to backend servers using PROXY protocol headers.

rank

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: primary, secondary

• Default: primary

• Description: Specifies the server's priority when making routing decisions.

replication_custom_options

• Type: string

• Default: None

• Dynamic: Yes

• Description: Defines custom options added to replication commands for server.

socket

• Type: string

• Mandatory: Yes, if address is not provided.

• Dynamic: Yes

• Default: ""

• Description: Specifies the Unix domain socket route that is used to establish a connection with the backend server.

use_service_credentials

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Manages whether service credentials are used for backend authentication before switching to the client user.

reference/maxscale-authenticators

maxscale-gssapi-client-authenticator

Settings

gssapi_keytab_path

• Type: path

• Mandatory: No

• Dynamic: No

• Default: Kerberos Default

• Description: Specifies the location of the GSSAPI authentication-related Kerberos keytab file.

principal_name

• Type: string

• Mandatory: No

• Dynamic: No

• Default: mariadb/localhost.localdomain

• Description: Defines the service principal name used in GSSAPI authentication.

maxscale-mariadb-mysql-authenticator

Settings

log_password_mismatch

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: false

• Description: Allows tracking of password hash mismatches during authentication.

maxscale-pam-authenticator

Settings

pam_backend_mapping

• Type: enumeration

• Mandatory: No

• Dynamic: No

• Values: none, mariadb

• Default: none

• Description: Manages the mapping of PAM-authenticated users to backend authentication.

pam_mapped_pw_file

• Type: path

• Mandatory: No

• Dynamic: No

• Default: None

• Description: Specifies a JSON file containing passwords for PAM-mapped users.

pam_mode

• Type: enumeration

• Mandatory: No

• Dynamic: No

• Values: password, password_2FA, suid

• Default: password

• Description: Defines the PAM authentication mode for client login.

pam_use_cleartext_plugin

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: false

• Description: Enables cleartext password authentication between the client and MaxScale when using PAM.

reference/maxscale-filters

maxscale-binlog-filter

Settings

exclude

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Excludes events, which match the specified regular expression.

match

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Includes only events that match the given regular expression.

rewrite_dest

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Specifies the replacement pattern that replication events use to rewrite statements.

rewrite_src

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Describes the pattern that is used to match statements in replication events for rewriting.

maxscale-cache

Settings

cache_in_transactions

• Type: enum

• Mandatory: No

• Dynamic: No

• Values: never, read_only_transactions, all_transactions

• Default: all_transactions

• Description: Manages how the cache is used and updated during transactions.

cached_data

• Type: enum

• Mandatory: No

• Dynamic: No

• Values: shared, thread_specific

• Default: thread_specific

• Description: Determines whether cached data remains thread-specific or shared across threads.

clear_cache_on_parse_errors

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: true

• Description: Controls whether the cache is cleared when modifying statements are not parsed correctly.

debug

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 0

• Description: Uses a bitmask value to control the cache's debug logging level.

enabled

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: true

• Description: Manages whether the cache is enabled or disabled at startup.

hard_ttl

• Type: duration

• Mandatory: No

• Dynamic: No

• Default: 0s (no limit)

• Description: Specifies how long cached data can last before being deleted and reloaded.

invalidate

• Type: enum

• Mandatory: No

• Dynamic: No

• Values: never, current

• Default: never

• Description: Manages how cached data is invalidated when changes occur.

max_count

• Type: count

• Mandatory: No

• Dynamic: No

• Default: 0 (no limit)

• Description: Specifies the maximum amount of data that cache can store.

max_resultset_rows

• Type: count

• Mandatory: No

• Dynamic: No

• Default: 0 (no limit)

• Description: Defines the maximum number of rows in a result set that can be cached.

max_resultset_size

• Type: size

• Mandatory: No

• Dynamic: No

• Default: 0 (no limit)

• Description: Specifies the maximum result set size that can be cached.

max_size

• Type: size

• Mandatory: No

• Dynamic: No

• Default: 0 (no limit)

• Description: Defines the maximum total size of the cache.

rules

• Type: path

• Mandatory: No

• Dynamic: Yes

• Default: "" (no rules)

• Description: Specifies the file path containing caching rules.

selects

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: assume_cacheable, verify_cacheable

• Default: assume_cacheable

• Description: Controls whether SELECT statements are considered to be cacheable or validated before caching.

soft_ttl

• Type: duration

• Mandatory: No

• Dynamic: No

• Default: 0s (no limit)

• Description: Determines how long cached data is used before being refreshed from the backend.

storage

• Type: string

• Mandatory: No

• Dynamic: No

• Default: storage_inmemory

• Description: Defines the storage module used by the cache.

storage_options

• Type: string

• Mandatory: No

• Dynamic: No

• Default:

• Description: Deprecated. Previously used to pass configuration options to the storage module.

timeout

• Type: duration

• Mandatory: No

• Dynamic: No

• Default: 5s

• Description: Specifies the timeout for processes involving external storage backends.

users

• Type: enum

• Mandatory: No

• Dynamic: No

• Values: mixed, isolated

• Default: mixed

• Description: Manages whether cached data is stored separately for each user or shared between users.

storage_memcached

max_value_size

• Type: size

• Mandatory: No

• Dynamic: No

• Default: 1Mi

• Description: Defines the maximum size of a value that can be stored in the cache.

server

• Type: The Memcached server address specified as host[:port]

• Mandatory: Yes

• Dynamic: No

• Description: Specifies the Memcached server address. The default port is 11211 is used when no port is provided.

storage_redis

password

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Password used for authentication.

server

• Type: The Redis server address specified as host[:port]

• Mandatory: Yes

• Dynamic: No

• Description: Defines the Redis server address. The default port is 6379 is used when no port is provided.

ssl

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: false

• Description: Enable SSL when connectign to the Redis server.

ssl_ca

• Type: Path to existing readable file.

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Specifies the CA certificate used to verify the Redis server certificate.

ssl_cert

• Type: Path to existing readable file.

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Defines the SSL client certificate used when connecting to the Redis server.

ssl_key

• Type: Path to existing readable file.

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Specifies the private key for the SSL client that is used to connect to the Redis server.

username

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Username used for authentication.

maxscale-comment-filter

Settings

inject

• Type: string

• Mandatory: Yes

• Dynamic: Yes

• Description: Specifies the comment injected before statements.

maxscale-consistent-critical-read-filter

Settings

count

• Type: count

• Mandatory: No

• Dynamic: Yes

• Default: 0

• Description: Defines the number of statements that are sent to the primary following a data-modifying statement.

global

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Manages whether write activity from a single connection affects routing behavior for all connections.

ignore

• Type: regex

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Defines a pattern for queries that should be ignored.

match

• Type: regex

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Specifies a pattern for statements that cause re-routing of statements.

options

• Type: enum

• Mandatory: No

• Dynamic: No

• Values: ignorecase, case, extended

• Default: ignorecase

• Description: Defines regular expression options used with match and ignore.

time

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 60s

• Description: Determines the time range during which statements are directed to the primary following a data-modifying statement.

maxscale-ldi-filter

Settings

host

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: s3.amazonaws.com

• Description: Specifies the S3 object storage host.

key

• Type: string

• Mandatory: No

• Dynamic: Yes

• Description: Defines the S3 access key used for authentication.

no_verify

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: TLS certificate verification is disabled for object storage when enabled.

port

• Type: integer

• Mandatory: No

• Dynamic: Yes

• Default: 0

• Description: Defines the port used to connect to the S3 object storage.

protocol_version

• Type: integer

• Mandatory: No

• Dynamic: Yes

• Default: 0

• Values: 0, 1, 2

• Description: Specifies the protocol version used to communicate with object storage.

region

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: us-east-1

• Description: Defines the S3 region that contains the data.

secret

• Type: string

• Mandatory: No

• Dynamic: Yes

• Description: Describes the S3 secret key that is used for verification.

use_http

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Enables unencrypted HTTP communication with the object storage when set to true.

maxscale-masking-filter

Settings

check_subqueries

• Type: bool

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Manages whether masking rules are applied to subqueries.

check_unions

• Type: bool

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Controls whether masking rules are applied to the UNION queries.

check_user_variables

• Type: bool

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Manages whether user variables are applied to user variables.

large_payload

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: ignore, abort

• Default: abort

• Description: Controls how payloads larger than 16MB are managed by the masking filter.

prevent_function_usage

• Type: bool

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Manages whether queries using functions on masked columns are rejected.

require_fully_parsed

• Type: bool

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Determines whether statements that cannot be fully parsed are rejected.

rules

• Type: path

• Mandatory: Yes

• Dynamic: Yes

• Description: Determines the path to the file containing masking rules.

treat_string_arg_as_field

• Type: bool

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Manages if functions' string parameters are managed as fields for masking.

warn_type_mismatch

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: never, always

• Default: never

• Description: Controls whether a column with an unsupported type is matched by a masking rule and whether a warning is logged.

maxscale-maxrows-filter

Settings

debug

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 0

• Description: Manages the level of debug logging for the MaxRows filter.

max_resultset_return

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: empty, error, ok

• Default: empty

• Description: Regulates the response that is sent to the client when the limitations defined by the results are exceeded.

max_resultset_rows

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: (no limit)

• Description: Specifies the maximum number of rows allowed in a result set returned to the client.

max_resultset_size

• Type: size

• Mandatory: No

• Dynamic: Yes

• Default: 64Ki

• Description: Restricts the size of a resultset that can be returned to the client; larger resultsets are replaced with an empty result.

maxscale-named-server-filter

Settings

matchXY

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Defines a numbered regex pattern to match SQL queries and apply a corresponding routing target when the pattern is matched.

options

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: ignorecase, case, extended

• Default: ignorecase

• Description: Describes the collection and matching process for the matchXY regular expressions (e.g., case sensitivity or extended syntax).

source

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Limits the filter to client connections from particular IP addresses or patterns; the regex rules will only be applied to sessions that match.

targetXY

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Defines the routing hint used to direct queries that match the corresponding matchXY pattern to specific server or roles.

user

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Limit the filters to sessions authenticated with a specific username; the routing hints and regex rules will only be applied to matching users.

maxscale-query-log-all-filter

Settings

append

• Type: bool

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Defines whether a new routing hint is added to existing ones or replaces them when applied to matching queries.

duration_unit

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: milliseconds

• Description: Defines the time unit used for logging durations.

exclude

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Defines a regex pattern to exclude queries from matching and filtering.

filebase

• Type: string

• Mandatory: Yes

• Dynamic: No

• Description: Specifies the base filename for session log files with unique session identifiers appended to create individual output files.

flush

• Type: bool

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Manages whether log files are immediately flushed to disk after each write operation.

log_data

• Type: enum_mask

• Mandatory: No

• Dynamic: Yes

• Values: service, session, date, user, reply_time, total_reply_time, query, default_db, num_rows, reply_size, transaction, transaction_time, num_warnings, error_msg

• Default: date, user, query

• Description: Specifies the fields, such as query details, user, timing, and execution metadata, that are present in each log entry.

log_type

• Type: enum_mask

• Mandatory: No

• Dynamic: Yes

• Values: session, unified, stdout

• Default: session

• Description: Defines the logging output type, such as per-session files, a unified log file, or standard output.

match

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Specifies a regex pattern for queries ti include and process by the filter.

newline_replacement

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: " "

• Description: Specifies the string that is used to substitute newline characters in logged queries so that the log output is consistent and readable.

options

• Type: enum_mask

• Mandatory: No

• Dynamic: Yes

• Values: case, ignorecase, extended

• Default: case

• Description: Defines the regex matching behavior (case sensitivity and extended syntax) for filter queries.

separator

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: ","

• Description: Specifies the string used to separate fields within each log entry.

source

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Limits logging to sessions that originate from specific client source addresses.

source_exclude

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Description: Defines a regex pattern for excluding requests from specified client IP addresses or hosts from logging.

source_match

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Description: Defines a regex pattern to include only queries from specific client IP addresses or hosts from logging.

use_canonical_form

• Type: bool

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Log queries in canonical format,replacing user-defined constants with placeholders to ensure consistent and secure output.

user

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Limits logging to sessions initiated by a specific username.

user_exclude

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Description: Defines a regex pattern that prevent requests from specific users from being logged.

user_match

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Description: Specifies a regex pattern to include queries only from specific users for logging.

maxscale-regex-filter

Settings

log_file

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Identifies a file where all queries, matched and unmatched, are logged, mainly for diagnostic purposes.

log_trace

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Allows runtime logging of matched and unmatched queries with replacements at the info level for diagnostic purposes.

match

• Type: regex

• Mandatory: Yes

• Dynamic: Yes

• Description: Defines the regex pattern in SQL statements that filter should identify and replace.

options

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: ignorecase, case, extended

• Default: ignorecase

• Description: Determines how the match regex pattern is compiled, including case sensitivity and extended syntax.

replace

• Type: string

• Mandatory: Yes

• Dynamic: Yes

• Description: Specifies the string that will replace SQL query parts that match the specific pattern.

source

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Restricts the match-and-replace filter to client connections originating from a specified address.

user

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Limits the match-and-replace filter to sessions initiated by a specific username.

maxscale-rewrite-filter

Settings

case_sensitive

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Defines whether template matching is case-sensitive by default.

log_replacement

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Allows logging of query replacements at the NOTICE level for monitoring and debugging.

regex_grammar

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: Native

• Values: Native, ECMAScript, Posix, EPosix, Awk, Grep, EGrep

• Description: Overrides the template's default regex grammar, allowing it to be used with alternative regex engines such as ECMAScript or Posix.

template_file

• Type: string

• Mandatory: Yes

• Dynamic: Yes

• Default: No default value

• Description: Specifies the file path to the template used by the filter.

Settings per template in the template file

case_sensitive

• Type: boolean

• Default: From maxscale.cnf

• Description: Overrides the global template configuration to specify whether pattern matching is case-sensitive.

continue_if_matched

• Type: boolean

• Default: false

• Description: Identifies whether to use subsequent templates on a query once the previous template has been matched and replaced.

ignore_whitespace

• Type: boolean

• Default: true

• Description: Specifies whether whitespace differences between the template and SQL inout should be ignored during matching.

regex_grammar

• Type: string

• Values: Native, ECMAScript, Posix, EPosix, Awk, Grep, EGrep

• Default: From maxscale.cnf

• Description: Defines the default tes such as Native, ECMAScript, and POSIX.

what_if

• Type: boolean

• Default: false

• Description: Simulates replacements without affecting queries and logs any possible changes to the NOTICE level.

maxscale-tee-filter

Settings

exclude

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Defines a regex pattern to exclude queries from processing or matching.

match

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Defines a regex pattern to include only queries that match it for processing or filtering.

options

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: ignorecase, case, extended

• Default: ignorecase

• Description: Determines how regular expressions are parsed, including case sensitivity and extended syntax.

service

• Type: service

• Mandatory: No

• Dynamic: Yes

• Default: none

• Description: Specifies the service for which queries are replicated; deprecated in favor of the target parameter.

source

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Limits query replication to sessions that start from a specific client IP address.

sync

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Allows synchronous routing, ensuring queries are executed on both the main and branch targets before continuing; branch failures close the client connection.

target

• Type: target

• Mandatory: No

• Dynamic: Yes

• Default: none

• Description: Specifies the branch target, which is the service or server where queries will be replicated.

user

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Restricts query replication to sessions initiated by a specific username.

maxscale-throttle-filter

Settings

continuous_duration

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 2s

• Description: Specifies the time interval used to decide when continuous throttling begins and finishes.

max_qps

• Type: number

• Mandatory: Yes

• Dynamic: Yes

• Description: Sets the maximum number of requests per second allowed for a session during the specific sample period.

sampling_duration

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 250ms

• Description: Defines the time interval during which queries per second (QPS) are mesaured for throttling purposes.

throttling_duration

• Type: duration

• Mandatory: Yes

• Dynamic: Yes

• Description: Specifies how long a session can be throttled before being disconnected by MaxScale.

maxscale-top-filter

Settings

count

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 10

• Description: Sets the number of SQL statements to store and include in the report.

exclude

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Defines a regex pattern that prevents the filter from logging specific queries.

filebase

• Type: string

• Mandatory: Yes

• Dynamic: Yes

• Description: Specifies the base name for session log files, followed by the session ID to generate unique output files.

match

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Defines a regex pattern that only logs requests that match it, while ignoring others.

options

• Type: enum

• Mandatory: No

• Dynamic: No

• Values: ignorecase, case, extended

• Default: case

• Description: Determines how the match and exlcude regex patterns are handled, including case sensitivity and extended syntax.

source

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Limits logging to sessions that start from a specific client IP address.

user

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Limits logging to sessions initiated by a specific username.

maxscale-workload-capture-and-replay

Settings

capture_dir

• Type: path

• Default: /var/lib/maxscale/wcar/

• Mandatory: No

• Dynamic: No

• Description: Specifies the directory in which session capture subdirectories are kept for each filter.

capture_duration

• Type: duration

• Default: 0s

• Maximum: Unlimited in MaxScale, 5min in MaxScale Lite.

• Mandatory: No

• Dynamic: No

• Description: Determines how long a session capture can run; a value of 0 indicates an infinite duration.

capture_size

• Type: size

• Default: 0

• Maximum: Unlimited in MaxScale, 10MB in MaxScale Lite.

• Mandatory: No

• Dynamic: No

• Description: Specifies the maximum session capture size in bytes; a value of 0 indicates no size restriction.

start_capture

• Type: boolean

• Default: false

• Mandatory: No

• Dynamic: No

• Description: Determines whether session capture starts automatically when MaxScale starts.

reference/maxscale-monitors

common-monitor-parameters

Settings

backend_connect_attempts

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 1

• Description: Specifies the maximum number of times MaxScale attempts to connect to a backend during each monitoring cycle.

backend_connect_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 3s

• Description: Sets the maximum amount of time allowed to connect to a backend server; deprecated in favor of backend timeout.

backend_read_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 3s

• Description: Specifies the timeout for reading query resuts from a backend server. Deprecated and ignored since MaxScale 25.08.0.

backend_write_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 3s

• Description: Deprecated and ignored since MaxScale 25.10.0.

disk_space_check_interval

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 0s

• Description: Sets the minimum interval between disk space checks; a value of 0 disables automatic checks.

disk_space_threshold

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Defines the disk usage limit (per path) that creates alerts. It can be set globally in the monitor or individually per server if disk configurations differ.

events

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: master_down, master_up, slave_down, slave_up, server_down, server_up, lost_master, lost_slave, new_master, new_slave

• Default: All events

• Description: Specifies which server events cause a script to execute; if not provided, it defaults to all events.

journal_max_age

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 28800s

• Description: Sets the maximum age of journal files; older files are deleted when the monitor starts.

module

• Type: string

• Mandatory: Yes

• Dynamic: No

• Description: Specifies which monitor module will be used, such as mariadbmon or orgaleramon.

monitor_interval

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 2s

• Description: Determines how often the monitor checks and updates the status of servers; shorter intervals result in more frequent checks.

password

• Type: string

• Mandatory: Yes

• Dynamic: Yes

• Description: Defines the password for the user defined in the user parameter; overrides older passwd settings.

primary_state_sql

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Specifies custom SQL commands to be executed on a primary (Master) server when it achieves Master status or when the monitor starts, allowing for role-based configuration changes.

replica_state_sql

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Specifies custom SQL commands to run on a replica (Slave) server when they get Slave status or when the monitor starts, allowing role-based configuration changes.

role

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Specifies a user role to activate when the monitor connects to a server, providing privilege separation between monitoring and service operations.

script

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Specifies a command to execute when the server status changes, with the help of placeholders (such as $INITIATOR, $EVENT, and $MASTERLIST) that MaxScale replaces with relevant server information; script output is reported based on message prefixes.

script_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 90s

• Description: Sets a maximum period of time a script can execute; if this limit exceeds the allowed duration, the script is issued SIGTERM, followed by SIGKILL if it does not stop.

servers

• Type: string

• Mandatory: Yes

• Dynamic: Yes

• Description: Provides a comma-separated list of servers that the monitor will track and manage.

user

• Type: string

• Mandatory: Yes

• Dynamic: Yes

• Description: Specifies the monitor's username for connecting to backend servers; if defined, this overrides the server's monitoruser.

galera-monitor

Settings

available_when_donor

• Type: boolean

• Default: false

• Dynamic: Yes

• Description: Allows Galera nodes to continue performing normal operations while acting as donors during non-blocking SST methods, preventing them from losing synchronized or read/write state.

disable_master_failback

• Type: boolean

• Default: false

• Dynamic: Yes

• Description: Prevents MaxScale from restoring the original node to primary status after a failover; the new primary retains the role while running.

disable_master_role_setting

• Type: boolean

• Default: false

• Dynamic: Yes

• Description: Disables automatic primary and replica role assignment in a Galera cluster; when enabled, only the Synced status is assigned.

root_node_as_master

• Type: boolean

• Default: false

• Dynamic: Yes

• Description: Ensures that only the Galera node with wsrep_local_index = 0 can be chosen as the primary for writes, enabling many MaxScale instances to use the same primary node.

set_donor_nodes

• Type: boolean

• Default: false

• Dynamic: Yes

• Description: Controls whether the wsrep_sst_donor global variable is set on each replica node, listing eligible donor nodes for SST in a sorted order based on priority or wsrep_local_index.

use_priority

• Type: boolean

• Default: false

• Dynamic: Yes

• Description: Allows the monitor to automatically select the writing node and manage controlled node replacements in a Galera cluster while keeping server priorities into account.

mariadb-monitor

Settings

assume_unique_hostnames

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: When enabled, the monitor assumes that the server hostnames and ports in the configuration match those provided by the servers, resulting in accurate topology identification and support for cluster actions such as failover and switching.

cooperative_monitoring_locks

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: none, majority_of_all, majority_of_running

• Default: none

• Description: Controls how a monitor achieves exclusive locks in multi-MaxScale configurations; decides whether a monitor becomes primary based on the majority of all servers, only running servers, or none at all.

enforce_read_only_servers

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Automatically sets read_only on any writable servers that are not the primary and are not under maintenance, ensuring that non-primary servers remain read-only.

enforce_read_only_slaves

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Automatically sets read_only flag on writable replica servers, allowing only privileged users to write; the primary server is unaffected.

enforce_writable_master

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Ensures that the primary server is always writable by automatically disabling read-only mode during monitoring.

failcount

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 5

• Description: Specifies how many consecutive monitor cycles a primary must fail before being considered down and requiring failover or primary reselection.

maintenance_on_low_disk_space

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: When disk space is low, non-primary servers are automatically put into maintenance mode, which stops them from being used for sessions or failover unless they are manually removed.

master_conditions

• Type: enum_mask

• Mandatory: No

• Dynamic: Yes

• Values: none, connecting_slave, connected_slave, running_slave, primary_monitor_master, disk_space_ok

• Default: primary_monitor_master, disk_space_ok

• Description: Specifies additional requirements for a server to be considered primary, such as the availability of connected or running replicas, sufficient disk space, or agreement with supporting monitors.

script_max_replication_lag

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: -1

• Description: Sets a replication lag threshold (in seconds) that executes the monitor script when exceeded (rlag_above) or returned below (rlag_below); negative values disable this feature.

slave_conditions

• Type: enum_mask

• Mandatory: No

• Dynamic: Yes

• Values: none, linked_master, running_master, writable_master, primary_monitor_master

• Default: none

• Description: Specifies additional requirements for a server to be identified as a Slave, such as being connected to a running or writable primary; several conditions can be coupled using an enum mask.

Settings for Backup operations

backup_storage_address

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Provides the backup storage server's hostname or IP address. The server does not have to run MariaDB or be monitored by MaxScale. MaxScale connects via SSH, and the storage must have enough disk space to accommodate all backups.

backup_storage_path

• Type: path

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Specifies the path to the backup storage host where backups will be saved. The SSH user specified in ssh_user must have full read and write access to this directory.

mariadb_backup_parallel

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 1

• Description: Defines the number of parallel threads to use while running mariadb-backup. This value is used as the --parallel=<val> for mariadb-backup --backup. Increasing this value can accelerate backups on systems with multiple CPUs and fast I/O.

mariadb_backup_use_memory

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: 1G

• Description: Specifies how much memory mariadb-backup should use during the --prepare phase. This value is specified with the --use-memory=<val>. Setting it to an empty string disables the option and allows mariadb-backup to utilize the internal default. Increasing RAM can accelerate backup preparation, especially for large datasets.

rebuild_port

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 4444

• Description: Specifies the TCP port on which the source server will listen for the rebuild (SST) connection during a state transfer. This port must be open (not blocked by firewalls) and free (not in use by another process). If another process uses the port when the rebuild begins, MaxScale will attempt to terminate it to free up the port.

ssh_check_host_key

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Manages whether MaxScale verifies the SSH host key when connecting to a backend server. When set to true, MaxScale requires that the backend server’s host key is already present in the known_hosts file of the user running MaxScale. This ensures the authenticity of the server during SSH connections.

ssh_keyfile

• Type: path

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Specifies the SSH private key file used by MaxScale to authenticate when connecting to backend servers.

ssh_port

• Type: number

• Mandatory: No

• Dynamic: Yes

• Default: 22

• Description: Uses port for SSH connections when executing remote commands on backend servers.

ssh_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 10s

• Description: Specifies the maximum duration allowed for SSH commands during a rebuild before timing out.

ssh_user

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Specifies the SSH username for logging in to backend servers to execute commands.

Settings for Cluster manipulation operations

auto_failover

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: true, on, yes, 1, false, off, no, 0, safe

• Default: false

• Description: Enables or disables automated primary failover, which allows MaxScale to select a new primary if the current one fails.

auto_rejoin

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Allows automatic redirection of servers to duplicate from the current primary, resulting in a 1-primary-N-replicas architecture.

demotion_sql_file

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Specifies a SQL file to execute when a server is downgraded; equivalent to promotion_sql_file.

enforce_simple_topology

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Promotes a 1-primary-N-replicas cluster configuration, automatically reconnecting servers and deleting unnecessary replication sources to maintain a simple topology.

failover_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 90s

• Description: Sets the maximum time allowed for a failover operation before it is terminated and automatic failover is disabled.

handle_events

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Manages whether the monitor tracks and updates scheduled events on servers during offers, demotions, and rejoins.

master_failure_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 10s

• Description: Specifies the duration MaxScale waits before considering a primary server as failed.

promotion_sql_file

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Specifies a file of SQL statements to execute on a server during promotion to primary.

replication_master_ssl

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Enables SSL encryption for replication by configuring generated replication commands to use secure connections.

replication_password

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Specifies the password used by the replication user for authentication.

replication_user

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

• Description: Specifies the username used for replication authentication when configuring replica connections.

servers_no_promotion

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: None

[switchover_on_low_disk_space\*\*](../reference/maxscale-monitors/mariadb-monitor.md#switchover_on_low_disk_space**)

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Lists the servers that are excluded from being promoted to primary during failover or automatic selection.

switchover_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 90s

• Description: Defines the maximum time allowed for switchover and rejoin operations before timing out.

verify_master_failure

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Enables verification of primary server failure using replica status before triggering automatic failover.

Settings for Primary server write test

write_test_fail_action

• Type: enum

• Default: log

• Values: log, failover

• Dynamic: Yes

• Description: Defines the action to consider when the primary fails a write text, either logging the failure or triggering a failover.

write_test_interval

• Type: duration

• Dynamic: Yes

• Default: 0s

• Description: Sets the interval after which a write test is performed on the primary if no changes are detected.

write_test_table

• Type: string

• Dynamic: Yes

• Default: mxs.maxscale_write_test

• Description: Specifies the fully qualified table used by the monitor to perform primary server write tests.

reference/maxscale-protocols

maxscale-mariadb-protocol-module

Settings

allow_replication

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Manages whether the replication protocol is permitted through this listener.

maxscale-nosql-protocol-module

Settings

authentication_db

• Type: string

• Mandatory: No

• Default: "NoSQL"

• Description: Specifies the database that stores NoSQL account information for authentication.

authentication_key_id

• Type: string

• Mandatory: No

• Default: ""

• Description: Specifies the encryption key ID used to encrypt NoSQL account information in the database.

authentication_password

• Type: string

• Mandatory: No

• Default: ""

• Description: Specifies the password for the NoSQL authentication user.

authentication_required

• Type: boolean

• Mandatory: No

• Default: false

• Description: Determines whether clients are required to authenticate before accessing the service.

authentication_shared

• Type: boolean

• Mandatory: No

• Default: false

• Description: Controls whether NoSQL account information is stored in a shared or private manner.

authentication_user

• Type: string

• Mandatory: Yes, if authentication_shared is true.

• Description: Specifies the user used to access and manage shared NoSQL account information.

authorization_enabled

• Type: boolean

• Mandatory: No

• Default: false

• Description: Enables or disables NoSQL protocol–level authorization for user management commands.

auto_create_databases

• Type: boolean

• Mandatory: No

• Default: true

• Description: Controls whether databases are automatically created when required.

auto_create_tables

• Type: boolean

• Mandatory: No

• Default: true

• Description: Controls whether tables are automatically created within existing databases when required.

cursor_timeout

• Type: duration

• Mandatory: No

• Default: 60s

• Description: Sets the maximum idle time before an inactive cursor is automatically closed.

debug

• Type: enum_mask

• Mandatory: No

• Values: none, in, out, back

• Default: none

• Description: Manages which protocol events are logged, including incoming commands, backend SQL, and client responses.

host

• Type: string

• Mandatory: No

• Default: "%"

• Description: Specifies the host portion of the MariaDB user account created via the NoSQL protocol.

id_length

• Type: count

• Mandatory: No

• Range: [35, 2048]

• *Default: 35

• Description: Sets the length of the id column for automatically created tables.

internal_cache

• Type: string

• Mandatory: No

• Default: ''

• Description: Specifies the internal cache to use, currently supporting only the cache filter.

log_unknown_command

• Type: boolean

• Mandatory: No

• Default: false

• Description: Determines whether unsupported or unknown client commands are logged for debugging.

on_unknown_command

• Type: enum

• Mandatory: No

• Values: return_error, return_empty

• Default: return_error

• Description: Defines how the system responds to unrecognized client commands, either with an error or an empty result.

ordered_insert_behavior

• Type: enum

• Mandatory: No

• Values: atomic, default

• Default: default

• Description: Controls whether multi-document inserts are performed completely or individually based on the ordered setting.

password

• Type: string

• Mandatory: No

• Default: ""

• Description: Specifies the password used for backend connections when the MongoDB client is unauthenticated.

user

• Type: string

• Mandatory: No

• Default: ""

• Description: Specifies the username used for backend connections when the MongoDB client is unauthenticated.

reference/maxscale-rest-api

maxscale-filter-resource

Resource Operations

[Create a filter](../reference/maxscale-rest-api/maxscale-filter-resource.md#Create a filter)

• Type of the object, must be filters

• data.attributes.module

• The filter module to use

maxscale-listener-resource

Resource Operations

[Create a new listener](../reference/maxscale-rest-api/maxscale-listener-resource.md#Create a new listener)

• Type of the object, must be listeners

• data.attributes.parameters.port OR data.attributes.parameters.socket

• The TCP port or UNIX Domain Socket the listener listens on. Only one of the fields can be defined.

• data.relationships.services.data

• The service relationships data, must define a JSON object with an id value that defines the service to use and a type value set to services.

maxscale-monitor-resource

Resource Operations

[Create a monitor](../reference/maxscale-rest-api/maxscale-monitor-resource.md#Create a monitor)

• Type of the object, must be monitors

• data.attributes.module

• The monitor module to use

• data.attributes.parameters.user

• The user to use

• data.attributes.parameters.password

• The password to use

maxscale-server-resource

Resource Operations

[Create a server](../reference/maxscale-rest-api/maxscale-server-resource.md#Create a server)

• Type of the object, must be servers

• data.attributes.parameters.address OR data.attributes.parameters.socket

• The address or socket to use. Only one of the fields can be defined.

• data.attributes.parameters.port

• The port to use. Needs to be defined if the address field is defined.

maxscale-service-resource

Resource Operations

[Create a service](../reference/maxscale-rest-api/maxscale-service-resource.md#Create a service)

• Type of the object, must be services

• data.attributes.router

• The router module to use

• data.attributes.parameters.user

• The user to use

• data.attributes.parameters.password

• The password to use

reference/maxscale-routers

maxscale-binlogrouter

Settings

archivedir

• Type: string

• Mandatory: Yes

• Default: No

• Dynamic: No

• Description: Specifies the directory where files are archived when expiration_mode is set to archive.

compression_algorithm

• Type: enum

• Mandatory: No

• Dynamic: No

• Values: none, zstandard

• Default: none

• Description: Defines the compression algorithm to use for archived files.

datadir

• Type: path

• Mandatory: No

• Dynamic: No

• Default: /var/lib/maxscale/binlogs

• Description: Shows the directory where binary log files are stored.

ddl_only

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: false

• Description: When enabled, only DDL events (CREATE, ALTER, DROP) are logged, excluding data changes.

encryption_cipher

• Type: enum

• Mandatory: No

• Dynamic: No

• Values: AES_CBC, AES_CTR, AES_GCM

• Default: AES_GCM

• Description: Defines the AES encryption mode used for securing data, such as GCM, CBC, or CTR.

encryption_key_id

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Specifies the encryption key ID used to encrypt binary logs, requiring a configured key manager.

expiration_mode

• Type: enum

• Dynamic: No

• Values: purge, archive

• Default: purge

• Description: Indicates whether expired logs are automatically deleted or archived.

expire_log_duration

• Type: duration

• Mandatory: No

• Dynamic: No

• Default: 0s

• Description: Sets the duration after which binary log files expire and are eligible for purge or archiving.

expire_log_minimum_files

• Type: number

• Mandatory: No

• Dynamic: No

• Default: 2

• Description: Determines the minimum number of binary log files to keep during automatic purging.

net_timeout

• Type: duration

• Mandatory: No

• Dynamic: No

• Default: 10s

• Description: Sets the network connection and read timeout for the primary server connection.

number_of_noncompressed_files

• Type: count

• Mandatory: No

• Dynamic: No

• Default: 2

• Description: Specifies the minimum number of binary log files to keep up uncompressed.

rpl_semi_sync_slave_enabled

• Type: boolean

• Mandatory: No

• Default: false

• Dynamic: Yes

• Description: Enables semi-synchronous replication from a MariaDB server by sending acknowledgements for received events.

select_master

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: false

• Description: Selects a primary server for replication automatically from a list of servers that are monitored and have Master status.

server_id

• Type: count

• Mandatory: No

• Dynamic: No

• Default: 1234

• Description: Mentions the server ID used by MaxScale for replication and serving binary logs to replicas.

maxscale-diff

Settings

explain

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: none, other, `both'

• Default: both

• Description: Determines whether queries are EXPLAINed on the main server, other servers, or both.

explain_entries

• Type: non-negative integer

• Mandatory: No

• Dynamic: Yes

• Default: 2

• Description: Sets the maximum number of times a canonical statement is EXPLAINed throughout the explain period.

explain_period

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 15m

• Description: Defines the time window over which the explain_entries limit applies for EXPLAIN operations.

main

• Type: server

• Mandatory: Yes

• Dynamic: No

• Description: Specifes the primary server from which query results are returned to the client.

max_request_lag

• Type: non-negative integer

• Mandatory: No

• Dynamic: Yes

• Default: 10

• Description: Sets the maximum allowed request la on replica servers before SELECTs are skipped to connect with the primary server.

on_error

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: close, ignore

• Default: ignore

• Description: Determines whether errors from replica servers close the session or are are ignored.

percentile

• Type: count

• Mandatory: No

• Dynamic: Yes

• Min: 1

• Max: 100

• Default: 99

• Description: Defines the percentile of samples used to calculate histogram width and bin count.

qps_window

• Type: duration

• Mandatory: No

• Dynamic: No

• Default: 15m

• Description: Specifies the time window over which queries per second (QPS) are calculated and logged.

report

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: always, on_discrepancy, never

• Default: on_discrepancy

• Description: Defines when results from main and other executions are logged: always, on discrepancy, or never.

reset_replication

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Controls whether replication on other is reset and restarted after a read-write Diff session completes.

retain_faster_statements

• Type: non-negative integer

• Mandatory: No

• Dynamic: Yes

• Default: 5

• Description: Sets how many of the fastest statements are kept in memory for summary reporting.

retain_slower_statements

• Type: non-negative integer

• Mandatory: No

• Dynamic: Yes

• Default: 5

• Description: Sets how many of the slowest statements are kept in memory for summary reporting.

samples

• Type: count

• Mandatory: No

• Dynamic: Yes

• Min: 100

• Default: 1000

• Description: Defines the number of samples collected to determine histrogram bin edges and counts.

service

• Type: service

• Mandatory: Yes

• Dynamic: No

• Description: Defines the service that Diff will operate on.

maxscale-exasolrouter

Settings

appearance

• Type: enum

• Mandatory: No

• Dynamic: No

• Values: read_only, read_write

• Default: read_only

• Description: Determines whether the Exasolrouter appears as read-only or read-write to other MaxScale components.

connection_string

• Type: string

• Mandatory: Yes

• Dynamic: No

• Description: Specifies the Exasol ODBC connection string used to connect to the database.

preprocessor

• Type: String

• Mandatory: No

• Dynamic: No

• Values: auto, activate-only, custom:<path>, disabled

• Default: auto

• Description: Defines how the Exasol preprocesser script is managed: auto-installed, activate-only, custom path, or disabled.

preprocessor_script

• Type: String

• Mandatory: No

• Dynamic: No

• Default: "UTIL.maria_preprocessor"

• Description: Specifies the name of a custom Exasol preprocessor script when using a custom preprocessor path.

maxscale-kafkacdc

Settings

bootstrap_servers

• Type: string

• Mandatory: Yes

• Dynamic: No

• Description: Specifies the list of Kafka brokers in host:port format for connecting to the cluster.

cooperative_replication

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: false

• Description: Enables coperative replication, allowing multiple MaxScale instances to replicate from the same cluster while ensuring each event is processed only once.

enable_idempotence

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: false

• Description: Enables idempotent Kafka producer mode to reduce duplicate message delivery and preserve message order.

exclude

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Excludes tables matching a specified pattern from being sent to Kafka.

gtid

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Specifies the initial GTID position for replication; supports newest and oldest special values.

kafka_sasl_mechanism

• Type: enum

• Mandatory: No

• Dynamic: No

• Values: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512

• Default: PLAIN

• Description: Specifies the SASL authentication mechanism for connecting to Kafka, such as PLAIN or SCRAM-SHA variants.

kafka_sasl_password

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Specifies the password used for SASL authentication with Kafka.

kafka_sasl_user

• Type: string

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Specifies the username used for SASL authentication with Kafka.

kafka_ssl

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: false

• Description: Enables SSL encryption for Kafka connections.

kafka_ssl_ca

• Type: path

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Specifies the path to the CA certificate file for SSL Kafka connections.

kafka_ssl_cert

• Type: path

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Specifies the path to the client SSL certificate file for Kafka connections.

kafka_ssl_key

• Type: path

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Specifies the path to the client SSL private key for Kafka connections.

match

• Type: regex

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Includes only tables whose combined database and table names match the specified pattern for Kafka replication.

read_gtid_from_kafka

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: true

• Description: Determines whether to read the latest GTID from Kafka on startup to resume replication.

send_schema

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Controls whether table schema change events are sent as JSON objects into the Kafka stream.

server_id

• Type: number

• Mandatory: No

• Dynamic: No

• Default: 1234

• Description: Specifies the server ID used when connecting to the primary for replication.

timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 10s

• Description: Defines the timeout for establishing and reading from the replication stream connection.

topic

• Type: string

• Mandatory: Yes

• Dynamic: No

• Description: Specifies the Kafka topic where replicated events are published.

maxscale-kafkaimporter

Settings

batch_size

• Type: count

• Mandatory: No

• Dynamic: Yes

• Default: 100

• Description: Defines the maximum number of records to buffer before committing a batch of imported data.

bootstrap_servers

• Type: string

• Mandatory: Yes

• Dynamic: Yes

• Description: Specifies the comma-separated list of Kafka broker addresses used to establish connections.

engine

• Type: string

• Default: InnoDB

• Mandatory: No

• Dynamic: Yes

• Description: Specifies the storage engine used when creating tables for imported Kafka data.

kafka_sasl_mechanism

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512

• Default: PLAIN

• Description: Specifies the SASL authentication mechanism used for Kafka connections.

kafka_sasl_password

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Specifies the SASL password for Kafka authentication, requiring a corresponding username.

kafka_sasl_user

• Type: string

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Specifies the SASL username for Kafka authentication, requiring a corresponding password.

kafka_ssl

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Enables or disables SSL encryption for Kafka connections.

kafka_ssl_ca

• Type: path

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Specifies the CA certificate file used to verify Kafka SSL connections, or defaults to the system CA.

kafka_ssl_cert

• Type: path

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Defines the SSL certificate file for Kafka connections, requiring a corresponding private key.

kafka_ssl_key

• Type: path

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Specifies the SSL private key file for Kafka connections, requiring a corresponding certificate.

table_name_in

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: topic, key

• Default: topic

• Description: Defines whether the Kafka topic or message key is used to determine the target table for data insertion.

timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 5000ms

• Description: Sets the timeout for network communication with both Kafka and MariaDB.

topics

• Type: stringlist

• Mandatory: Yes

• Dynamic: Yes

• Description: Specifies the comma-separated list of topics to subscribe to.

maxscale-mirror

Settings

exporter

• Type: enum

• Mandatory: Yes

• Dynamic: Yes

• Values: log, file, kafka

• Description: Specifies the destination where metrics are exported, such as log, file, or Kafka.

file

• Type: string

• Default: No default value

• Mandatory: No

• Dynamic: Yes

• Description: Specifies the file path where metrics are written when the file exporter is enabled.

kafka_broker

• Type: string

• Default: No default value

• Mandatory: No

• Dynamic: Yes

• Description: Specifies the list of Kafka brokers used to send metrics when the Kafka exporter is enabled.

kafka_topic

• Type: string

• Default: No default value

• Mandatory: No

• Dynamic: Yes

• Description: Specifies the Kafka topic used to publish metrics when the Kafka exporter is enabled.

main

• Type: target

• Mandatory: Yes

• Dynamic: Yes

• Description: Defines the primary target server whose results are returned to the client and whose availability is required for the session.

on_error

• Type: enum

• Default: ignore

• Mandatory: No

• Dynamic: Yes

• Values: ignore, close

• Description: Defines how backend connection failures are handled, either by ignoring them or closing the client connection.

report

• Type: enum

• Default: always

• Mandatory: No

• Dynamic: Yes

• Values: always, on_conflict

• Description: Determines when query results are reported to the client, either always or only on conflicts.

maxscale-readconnroute

Settings

master_accept_reads

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Determines whether read queries are routed to the primary server when selecting servers.

max_replication_lag

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 0s

• Description: Sets the maximum allowed replication lag for a server to be used for routing.

router_options

• Type: enum_mask

• Mandatory: No

• Dynamic: Yes

• Values: master, slave, synced, running

• Default: running

• Description: Specifies which server roles are eligible for connections when establishing new router sessions.

maxscale-readwritesplit

Settings

causal_reads

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: none, local, global, fast, fast_global, universal, fast_universal

• Default: none

• Description: Controls causal read behavior to ensure reads reflect prior writes despite replication lag.

causal_reads_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 10s

• Description: Defines how long to wait for replica synchronization when using causal reads before timing out.

delayed_retry

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Enables retrying failed queries for a limited time before returning an error if no server becomes available.

delayed_retry_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 10s

• Description: Specifies how long to wait before returning an error to the client when delayed retries are enabled.

lazy_connect

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Enables on-demand creation of backend connections instead of opening all connections at session start.

master_accept_reads

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Determines whether the primary server can be used to handle read queries alongside replicas.

master_failure_mode

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: fail_instantly, fail_on_write, error_on_write

• Default: fail_on_write (MaxScale 23.08: fail_instantly)

• Description: Defines how the router handles primary server failure and client behavior during write operations.

master_reconnection

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true (>= MaxScale 24.02), false(<= MaxScale 23.08)

• Description: Controls whether a session can reconnect to a new primary server if the current one becomes unavailable.

max_replication_lag

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 0s

• Description: Sets the maximum allowed replication lag for replicas to be eligible for routing read queries.

max_slave_connections

• Type: integer

• Mandatory: No

• Dynamic: Yes

• Min: 0

• Max: 255

• Default: 255

• Description: Limits the maximum number of replica connections a session can use simultaneously.

retry_failed_reads

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Determines whether failed autocommit read queries are retried on another replica.

slave_connections

• Type: integer

• Mandatory: No

• Dynamic: Yes

• Default: 255

• Description: Specifies the initial number of replica connections a session creates for routing read queries.

slave_selection_criteria

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: least_current_operations, adaptive_routing, least_behind_master, least_router_connections, least_global_connections

• Default: least_current_operations

• Description: Defines the criteria used to select replica servers for routing read queries and balancing load.

strict_multi_stmt

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Ensures that all queries after a multi-statement query are routed to the primary to maintain session consistency.

strict_sp_calls

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Ensures that queries following a stored procedure call are routed to the primary to maintain consistency.

strict_tmp_tables

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true (>= MaxScale 24.02), false (<= MaxScale 23.08)

• Description: Controls whether temporary tables block reconnections, ensuring they are not lost during primary node failovers.

sync_transaction

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: none, soft, hard

• Default: none

• Description: Defines how transactions are synchronized across replicas, with options for no synchronization, soft (non-blocking), or hard (blocking) synchronization.

sync_transaction_count

• Type: integer

• Mandatory: No

• Dynamic: Yes

• Min: 1

• Max: 255

• Default: 1

• Description: Specifies the minimum number of backend servers required to understand a transaction before it is considered committed.

sync_transaction_max_lag

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 0s

• Description: Sets the maximum allowed transaction synchronization latency in soft mode before triggering synchronization.

sync_transaction_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 10s

• Description: Sets the maximum time a transaction waits for synchronization before returning or closing the connection.

transaction_replay

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Enables replay of interrupted transactions, automatically retrying them on a replacement server if the current one fails.

transaction_replay_attempts

• Type: integer

• Mandatory: No

• Dynamic: Yes

• Default: 5

• Description: Determines the maximum number of times a transaction will be retried during replay before failing.

transaction_replay_checksum

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: full, result_only, no_insert_id

• Default: full

• Description: Specifies the method for calculating transaction checksums to verify replayed transactions; full ensures complete consistency.

transaction_replay_max_size

• Type: size

• Mandatory: No

• Dynamic: Yes

• Default: 1 MiB

• Description: Sets the maximum transaction size (in bytes) that can be replayed; larger transactions are not replayed.

transaction_replay_retry_on_deadlock

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Automatically retries transactions that encounter a deadlock until they succeed or a checksum error occurs.

transaction_replay_retry_on_mismatch

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Retries transactions that fail due to checksum mismatches during replay, subject to the set limits.

transaction_replay_safe_commit

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: true

• Description: Prevents replaying transactions that are about to commit to avoid duplicates; enabled by default.

transaction_replay_timeout

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 30s (>= MaxScale 24.02), 0s (<= MaxScale 23.08)

• Description: Sets the maximum duration for attempting transaction replay; set to 0 to disable.

use_sql_variables_in

• Type: enum

• Mandatory: No

• Dynamic: Yes

• Values: master, all

• Default: all

• Description: Controls which nodes handle SELECT statements using SQL user variables; defaults to all nodes.

maxscale-schemarouter

Settings

allow_duplicates

• Type: boolean

• Mandatory: No

• Dynamic: Yes

• Default: false

• Description: Disables the detection of duplicate tables on shards while it is enabled.

ignore_tables

• Type: stringlist

• Mandatory: No

• Dynamic: Yes

• Default: ""

• Description: Specifies a list of full table names to ignore when checking for duplicate tables.

ignore_tables_regex

• Type: regex

• Mandatory: No

• Dynamic: No

• Default: ""

• Description: Defines a PCRE2 regular expression to ignore specific tables when checking for duplicate databases.

max_staleness

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 150s

• Description: Specifies how long stale database map entries can be used by new connections while an update is in progress.

refresh_databases

• Type: boolean

• Mandatory: No

• Dynamic: No

• Default: false

• Description: Allows the database map to be refreshed when a USE... query fails during a session.

refresh_interval

• Type: duration

• Mandatory: No

• Dynamic: Yes

• Default: 300s

• Description: Sets the minimum interval between database map refreshes to maintain cluster metadata up to date.

maxscale-smartrouter

Settings

master

• Type: target

• Mandatory: Yes

• Dynamic: No

• Description: Identifies the primary target cluster to which all write operations are directed.

---

_{This page is licensed: CC BY-SA / Gnu FDL}