Release Notes for MariaDB MaxScale 23.02.1

Inbound Proxy Protocol

MariaDB MaxScale 23.02 adds support for listeners to receive inbound proxy protocol traffic from other MaxScale nodes or from other load balancers, which allows authentication to be simplified when another MaxScale node or another load balancer is relaying client connections to MaxScale. (MXS-3003)

In previous releases, MaxScale supported outbound proxy protocol traffic between MaxScale and the database nodes, but it did not support inbound proxy protocol traffic for listeners.

Starting with this release, MaxScale listeners can receive inbound proxy protocol traffic if the proxy_protocol_networks parameter is configured for the listener. Set the proxy_protocol_networks parameter to a comma-separated list of IP addresses and subnets that are authorized to send proxy protocol traffic to the listener:

[rw-listener]
type=listener
service=rw-service
protocol=MariaDBClient
port=3306
proxy_protocol_networks=192.168.0.1,198.168.0.0/16

• Subnets must be in CIDR format (such as 192.168.0.0/16)

• A wildcard (*) allows proxy protocol traffic from any address

• localhost allows proxy protocol traffic from domain socket connections

When a MaxScale listener receives proxy protocol traffic from another MaxScale node or another load balancer, the proxy header contains the original client IP address and port. MaxScale use the original client IP address for authentication. If outbound proxy protocol traffic is also enabled between the MaxScale node and the database nodes, MaxScale uses a proxy header to relay the original client IP address and port to the database nodes as well. If the proxy protocol is used between the MaxScale node and the other load balancer and between the MaxScale node and the database nodes, both the MaxScale node and the database nodes know the original client IP address and port, and both can use this information for authentication.

Since the proxy protocol affects authentication, only trusted IP addresses and subnets should be added to the proxy_protocol_networks parameter.

When the proxy protocol is enabled for a listener, the listener still accepts connections that do not use the proxy protocol.

Backup and Restore for MariaDB Monitor

MariaDB MaxScale 23.02 adds support to MariaDB Monitor (mariadbmon) for the async-create-backup and async-restore-from-backup module commands, which can be used to create and restore backups. (MXS-3262)

[mdb-monitor]
type=monitor
module=mariadbmon
servers=server1,server2,server3
user=database_user
password=database_pwd
backup_storage_address=192.0.2.1
backup_storage_path=/backups
ssh_user=backup_admin
ssh_keyfile=/home/maxscale/.ssh/id_rsa
ssh_port=44

$ maxctrl call command mariadbmon async-create-backup mdb-monitor server1 20230222161011-backup-mdb-monitor-server1

$ maxctrl call command mariadbmon async-restore-from-backup mdb-monitor server2 20230222161011-backup-mdb-monitor-server1

$ maxctrl call command mariadbmon fetch-cmd-result mdb-monitor

Preserve Replication Position

MariaDB MaxScale 23.02 adds support to MariaDB Monitor (mariadbmon) for preserving the value of the MASTER_USE_GTID option after a switchover or failover. (MXS-4398)

When changing the primary on a node that was already a replica node, MariaDB Monitor uses the value of MASTER_USE_GTID that was being used prior to the switchover or failover.

When configuring replication on a node that was previously the primary node, MariaDB Monitor uses MASTER_USE_GTID=current_pos.

Dynamic Worker Thread Changes

MariaDB MaxScale 23.02 adds support for dynamically changing the number of worker threads used to route client traffic without restarting MaxScale. (MXS-3269)

As part of this change, MaxScale no longer assumes that the number of CPUs on the system is a constant value. This change helps improve MaxScale support in environments using virtualization or containerization, where the the number of CPUs available can be changed.

To change the number of worker threads dynamically, change the value of the threads parameter using the maxctrl alter maxscale sub-command:

$ maxctrl alter maxscale threads=2

The new threads_max parameter can be used to configure the hard limit for the number of worker threads. The default value is 256. The threads_max parameter can't be changed dynamically.

On startup, if the value of the threads configuration parameter is greater than the value of threads_max, the value of threads is reduced to the value of threads_max, and a warning is raised:

MaxScale can have at most THREADS_HARD_LIMIT routing threads; the request for THREADS_REQUESTED will be reduced to that. The maximum can be increased with `threads_max`.

At runtime, if the value of threads is set higher than the value of threads_max, an error is raised:

MaxScale can have at most THREADS_HARD_LIMIT routing threads; a request for THREADS_REQUESTED cannot be honored. The maximum can be increased with `threads_max`.

Cache Filter Enhancements

MariaDB MaxScale 23.02 contains some enhancements to the Cache Filter (cache).

$ maxctrl alter filter rw-cache rules='/path/to/rules-file'

[rw-cache]
type=filter
module=cache
storage=storage_redis
storage_options = "server=127.0.0.1, username=alice, password=PASSWORD"

[rw-service]
type=service
router=readwritesplit
servers=server1,server2,server3
user=mxs
password=PASSWORD
filters=rw-cache

[rw-listener]
type=listener
service=rw-cache
protocol=mariadbclient
port=3306

[rw-cache]
type=filter
module=cache
storage=storage_redis
storage_options = "server=127.0.0.1, ssl=true, ssl_cert=/etc/ssl/maxscale/mxs-cert.pem, ssl_key=/etc/ssl/maxscale/mxs-key.pem, ssl_ca=/etc/ssl/maxscale/ca.pem"

[rw-service]
type=service
router=readwritesplit
servers=server1,server2,server3
user=mxs
password=PASSWORD
filters=rw-cache

[rw-listener]
type=listener
service=rw-cache
protocol=mariadbclient
port=3306

Query Log All (QLA) Filter Enhancements

MariaDB MaxScale 23.02 adds support to the QLA Filter for filtering users and sources with regular expressions (regex). (MXS-4302)

The following parameters can be used:

• user_match: Only log queries from users that match this pattern. If the user parameter is used, the value of user_match is ignored.

  user_match=/(^alice$)|(^bob$)/
  

• user_exclude: Exclude all queries from users that match this pattern. If the user parameter is used, the value of user_exclude is ignored.

  user_exclude=/(^alice$)|(^bob$)/
  

• source_match: Only log queries from hosts that match this pattern. If the source parameter is used, the value of source_match is ignored.

  source_match=/(^127[.]0[.]0[.]1)|(^192[.]168[.]0[.]109)/
  

• source_exclude: Exclude all queries from hosts that match this pattern. If the source parameter is used, the value of source_exclude is ignored.

  source_exclude=/(^127[.]0[.]0[.]1)|(^192[.]168[.]0[.]109)/
  

Semi-Synchronous Replication for Binlog Router

MariaDB MaxScale 23.02 adds support for semi-synchronous replication to the Binlog Router. (MXS-3004)

With semi-synchronous replication, the primary server waits to commit a transaction until one replica server has acknowledged that they have received and logged the event. In previous releases of MaxScale, the Binlog Router is not able to provide this acknowledgment.

Starting with this release, when semi-synchronous replication is enabled on the primary server, the Binlog Router is able to provide the acknowledgments to the primary server. The router automatically detects when semi-synchronous replication is enabled on the primary server and automatically provides the correct acknowledgments. No special configuration is required in MaxScale.

Audit Log for REST API

MariaDB MaxScale 23.02 adds support for an audit log for the REST API. (MXS-3827)

The following parameters have been added to configure this feature:

To dynamically configure the parameters without restarting MaxScale, use the maxctrl alter maxscale sub-command:

$ maxctrl alter maxscale admin_audit_file=/var/log/maxscale/2023-02-admin_audit.csv

$ maxctrl alter maxscale admin_audit=true

Similar to the MaxScale log, the audit log for the REST API can also be rotated. However, unlike the MaxScale log, the audit log for the REST API is never overwritten when a rotation occurs.

ed25519 Authentication

MaxScale 23.02 adds support for ed25519 authentication. (MXS-4270)

MaxScale's ed25519 authentication is compatible with the ed25519 authentication plugin from MariaDB Enterprise Server.

When a client authenticates with MaxScale using ed25519, the following exchange occurs:

1. MaxScale transmits a random message to the client.

2. The client signs the message using the password as the private key and transmits the signature to MaxScale.

3. MaxScale verifies the signature using the public key stored for the user.

Throughout this exchange, the client's password is never transmitted to MaxScale.

This authentication method does have a downside for MaxScale. MaxScale requires a password to login to the database nodes on behalf of the client. Since MaxScale never receives the client's password, one of the following options is required:

• Option 1: MaxScale must store the password somewhere

• Option 2: MaxScale must use a different authentication method between the client and MaxScale, so that MaxScale can obtain the password from the client

MaxScale's implementation of ed25519 authentication supports both alternatives. Option 1 is ed_mode=ed25519 and option 2 is ed_mode=sha256.

[rw-listener]
type=listener
address=::
service=rw-service
authenticator=ed25519auth
authenticator_options="ed_mode=ed25519"
user_mapping_file=/etc/maxscale/user_mapping.json

{
   "user_map": [
      {
         "original_user": "alice",
         "mapped_user": "dba"
      },
      {
         "original_user": "bob",
         "mapped_user": "dba"
      }
   ],
   "server_credentials": [
      {
         "mapped_user": "dba",
         "password": "PASSWORD",
         "plugin": "mysql_native_password"
      },
      {
         "mapped_user": "carol",
         "password": "PASSWORD",
         "plugin": "mysql_native_password"
      }
   ]
}

[rw-listener]
type=listener
address=::
service=rw-service
authenticator=ed25519auth
authenticator_options="ed_mode=sha256,ed_rsa_privkey_path=/etc/ssl/maxscale/sha_private_key.pem,ed_rsa_pubkey_path=/etc/ssl/maxscale/sha_public_key.pem"

[rw-listener]
type=listener
address=::
service=rw-service
authenticator=ed25519auth
authenticator_options="ed_mode=sha256"
ssl=true
ssl_key=/etc/ssl/maxscale/mxs-key.pem
ssl_cert=/etc/ssl/maxscale/mxs-cert.pem
ssl_ca=/etc/ssl/maxscale/ca.pem

Monitor Session I/O Load

MaxScale 23.02 adds support for displaying I/O activity for each session and the relative I/O compared to the total I/O of all sessions. (MXS-4182)

The new details are available in the following interfaces:

• MaxGUI exposes the metric in the new I/O Activity column has been added to the Current Sessions window

• maxctrl list sessions exposes the metric in the new I/O Activity column

• maxctrl show sessions exposes the metric in the new I/O Activity row

• The REST API exposes the metric in the new io_activity attribute of the session object

The I/O activity metric is calculated using the number of I/O operations performed by the session during the previous 30 seconds. Since the value is an aggregate of I/O activity over the previous 30 seconds, very short peaks might not appear in the data.

Xpand Parallel Replication

MariaDB MaxScale 23.02 adds support for Xpand parallel replication to Read/Write Split Router (readwritesplit) and ReadConnRoute Router (readconnroute). (MXS-4330)

With Xpand parallel replication, Xpand uses multiple Slave Event Readers / Applicators on multiple nodes to independently stream and apply replication traffic. Since each Slave Event Reader / Applicator operates independently in parallel, the full power of the cluster is used without any choke points. When compared to serial replication, Xpand's parallel replication is more effective at keeping up with high write rates while reducing latency and slave lag.

Using MaxScale as a load balancer for Xpand parallel replication provides some operational benefits, including:

• MaxScale can automatically distribute Slave Event Reader / Applicator connections between multiple Xpand nodes to spread out load

• If an Xpand node fails, MaxScale can detect the failure and re-route failed replication connections to healthy nodes

CREATE SLAVE parallel_repl
   PARALLEL_LOG = xpand-bin,
   PARALLEL_POS = 0,
   SLICES = 6,
   BATCH_SIZE_MS = 1000,
   MASTER_HOST = MAXSCALE_ADDRESS,
   MASTER_PORT = MAXSCALE_PORT,
   MASTER_USER = repl,
   MASTER_PASSWORD =  PASSWORD;

Removed Deprecated Monitors

In MariaDB MaxScale 23.02, some deprecated monitors were removed:

• ColumnStore Monitor (csmon) has been removed, because MariaDB Monitor (mariadbmon) is the monitor used for MariaDB Enterprise ColumnStore 1.5 and later.

• Aurora Monitor (auroramon) has been removed, because it is no longer supported.

maxctrl Enhancements

MariaDB MaxScale 23.02 contains some enhancements for MaxCtrl.

$ maxctrl create monitor mdb_monitor mariadbmon \
   --monitor-user mxs \
   --monitor-password 'maxscale_passwd' \
   replication_user='repl_user' \
   replication_password='repl_pass' \
   --servers node1 node2 node3

$ maxctrl create monitor mdb_monitor mariadbmon \
   user='mxs' \
   password='maxscale_passwd' \
   replication_user='repl_user' \
   replication_password='repl_pass' \
   --servers node1 node2 node3

MaxGUI Enhancements

MariaDB MaxScale 23.02 adds enhancements for MaxGUI, including:

• MaxGUI includes a ETL/Data Migration service GUI. (MXS-4430)

• The Query Editor schema sidebar displays views, functions, triggers and indexes in addition to tables and procedures. (MXS-4013)

• MaxGUI remembers and restores user settings such as window sizes from a previous session. (MXS-4285)

Issues Fixed

Interface Changes

• admin_audit global parameter added

• admin_audit_exclude_methods global parameter added

• admin_audit_file global parameter added

• admin_jwt_max_age global parameter added

• auroramon monitor removed

• cluster maxctrl utility removed

• cluster diff maxctrl utility removed

• cluster sync maxctrl utility removed

• config_sync_db global parameter added

• csmon monitor removed

• drain maxctrl utility removed

• drain server maxctrl utility removed

• ED25519 authenticator plugin added

• grmon monitor removed

• insertstream filter removed

• maxctrl+create+listener --authenticator command-line option removed

• maxctrl+create+listener --authenticator-options command-line option removed

• maxctrl+create+listener --interface command-line option removed

• maxctrl+create+listener --protocol command-line option removed

• maxctrl+create+listener --tls-ca-cert command-line option removed

• maxctrl+create+listener --tls-cert command-line option removed

• maxctrl+create+listener --tls-cert-verify-depth command-line option removed

• maxctrl+create+listener --tls-crl command-line option removed

• maxctrl+create+listener --tls-key command-line option removed

• maxctrl+create+listener --tls-verify-peer-certificate command-line option removed

• maxctrl+create+listener --tls-verify-peer-host command-line option removed

• maxctrl+create+listener --tls-version command-line option removed

• maxctrl+create+monitor --monitor-password command-line option removed

• maxctrl+create+monitor --monitor-user command-line option removed

• maxctrl+create+server --authenticator command-line option removed

• maxctrl+create+server --authenticator-options command-line option removed

• maxctrl+create+server --protocol command-line option removed

• maxctrl+create+server --tls command-line option removed

• maxctrl+create+server --tls-ca-cert command-line option removed

• maxctrl+create+server --tls-cert command-line option removed

• maxctrl+create+server --tls-cert-verify-depth command-line option removed

• maxctrl+create+server --tls-key command-line option removed

• maxctrl+create+server --tls-verify-peer-certificate command-line option removed

• maxctrl+create+server --tls-verify-peer-host command-line option removed

• maxctrl+create+server --tls-version command-line option removed

• maxctrl+drain --drain-timeout command-line option removed

• maxctrl+drain+server --drain-timeout command-line option removed

• maxscale.maxscale admin_audit module parameter added

• maxscale.maxscale admin_audit_exclude_methods module parameter added

• maxscale.maxscale admin_audit_file module parameter added

• maxscale.maxscale admin_jwt_max_age module parameter added

• maxscale.maxscale config_sync_db module parameter added

• maxscale.maxscale threads_max module parameter added

• Monitor.mariadbmon backup_storage_address module parameter added

• Monitor.mariadbmon backup_storage_path module parameter added

• Protocol.MariaDBProtocol proxy_protocol_networks module parameter added

• threads_max global parameter added

Platforms

In alignment to the MariaDB Corporation Engineering Policy, MariaDB MaxScale 23.02.1 is provided for:

• CentOS 7 (x86_64)

• Debian 9 (x86_64, ARM64)

• Debian 10 (x86_64, ARM64)

• Debian 11 (x86_64, ARM64)

• Red Hat Enterprise Linux 7 (x86_64)

• Red Hat Enterprise Linux 8 (x86_64, ARM64)

• Red Hat Enterprise Linux 9 (x86_64, ARM64)

• Rocky Linux 8 (x86_64, ARM64)

• Rocky Linux 9 (x86_64, ARM64)

• SUSE Linux Enterprise Server 15 (x86_64, ARM64)

• Ubuntu 18.04 (x86_64, ARM64)

• Ubuntu 20.04 (x86_64, ARM64)

• Ubuntu 22.04 (x86_64, ARM64)

Installation

• Deploy Xpand Topology with MariaDB MaxScale 23.02

• Deploy Enterprise Cluster Topology with MariaDB MaxScale 23.02Deploy Enterprise Cluster Topology with MariaDB MaxScale 23.02

• Deploy Primary/Replica Topology with MariaDB MaxScale 23.02Deploy Primary/Replica Topology with MariaDB MaxScale 23.02

• Deploy ColumnStore Object Storage Topology with MariaDB MaxScale 23.02Deploy ColumnStore Object Storage Topology with MariaDB MaxScale 23.02

• Deploy ColumnStore Shared Local Storage Topology with MariaDB MaxScale 23.02Deploy ColumnStore Shared Local Storage Topology with MariaDB MaxScale 23.02

Upgrades

• Upgrade to MariaDB MaxScale 23.02