This is a read-only copy of the MariaDB Knowledgebase generated on 2024-11-14. For the latest, interactive version please visit https://mariadb.com/kb/.

MaxCtrl

MaxCtrl

MaxCtrl is a command line administrative client for MaxScale which uses the MaxScale REST API for communication. It is intended to be the replacement software for the legacy MaxAdmin command line client.

By default, the MaxScale REST API listens on port 8989 on the local host. The default credentials for the REST API are admin:mariadb. The users used by the REST API are the same that are used by the MaxAdmin network interface. This means that any users created for the MaxAdmin network interface should work with the MaxScale REST API and MaxCtrl.

For more information about the MaxScale REST API, refer to the REST API documentation and the Configuration Guide.

Commands

Options

All command accept the following global options.

  -u, --user      Username to use                    [string] [default: "admin"]
  -p, --password  Password for the user. To input the password manually, give -p
                  as the last argument or use --password=''
                                                   [string] [default: "mariadb"]
  -h, --hosts     List of MaxScale hosts. The hosts must be in HOST:PORT format
                  and each value must be separated by a comma.
                                            [string] [default: "localhost:8989"]
  -t, --timeout   Request timeout in milliseconds      [number] [default: 10000]
  -q, --quiet     Silence all output                  [boolean] [default: false]
  --tsv           Print tab separated output          [boolean] [default: false]

HTTPS/TLS Options:
  -s, --secure                  Enable HTTPS requests [boolean] [default: false]
  --tls-key                     Path to TLS private key                 [string]
  --tls-passphrase              Password for the TLS private key        [string]
  --tls-cert                    Path to TLS public certificate          [string]
  --tls-ca-cert                 Path to TLS CA certificate              [string]
  -n, --tls-verify-server-cert  Whether to verify server TLS certificates
                                                       [boolean] [default: true]

Options:
  --version  Show version number                                       [boolean]
  --help     Show help                                                 [boolean]

If no commands are given, maxctrl is started in interactive mode. Use `exit` to
exit the interactive mode.

list

Usage: list <command>

Commands:
  servers              List servers
  services             List services
  listeners <service>  List listeners of a service
  monitors             List monitors
  sessions             List sessions
  filters              List filters
  modules              List loaded modules
  threads              List threads
  users                List created users
  commands             List module commands

list servers

Usage: list servers

List all servers in MaxScale.

Field Description
Server Server name
Address Address where the server listens
Port The port on which the server listens
Connections Current connection count
State Server state
GTID Current value of @@gtid_current_pos

list services

Usage: list services

List all services and the servers they use.

Field Description
Service Service name
Router Router used by the service
Connections Current connection count
Total Connections Total connection count
Servers Servers that the service uses

list listeners

Usage: list listeners <service>

List listeners for a service.

Field Description
Name Listener name
Port The port where the listener listens
Host The address or socket where the listener listens
State Listener state

list monitors

Usage: list monitors

List all monitors in MaxScale.

Field Description
Monitor Monitor name
State Monitor state
Servers The servers that this monitor monitors

list sessions

Usage: list sessions

List all client sessions.

Field Description
Id Session ID
User Username
Host Client host address
Connected Time when the session started
Idle How long the session has been idle, in seconds
Service The service where the session connected

list filters

Usage: list filters

List all filters in MaxScale.

Field Description
Filter Filter name
Service Services that use the filter
Module The module that the filter uses

list modules

Usage: list modules

List all currently loaded modules.

Field Description
Module Module name
Type Module type
Version Module version

list threads

Usage: list threads

List all worker threads.

Field Description
Id Thread ID
Current FDs Current number of managed file descriptors
Total FDs Total number of managed file descriptors
Load (1s) Load percentage over the last second
Load (1m) Load percentage over the last minute
Load (1h) Load percentage over the last hour

list users

Usage: list users

List network the users that can be used to connect to the MaxScale REST API as well as enabled local accounts.

Field Description
Name User name
Type User type
Privileges User privileges

list commands

Usage: list commands

List all available module commands.

Field Description
Module Module name
Commands Available commands

show

Usage: show <command>

Commands:
  server <server>    Show server
  servers            Show all servers
  service <service>  Show service
  services           Show all services
  monitor <monitor>  Show monitor
  monitors           Show all monitors
  session <session>  Show session
  sessions           Show all sessions
  filter <filter>    Show filter
  filters            Show all filters
  module <module>    Show loaded module
  modules            Show all loaded modules
  maxscale           Show MaxScale information
  thread <thread>    Show thread
  threads            Show all threads
  logging            Show MaxScale logging information
  commands <module>  Show module commands of a module

show server

Usage: show server <server>

Show detailed information about a server. The Parameters field contains the currently configured parameters for this server. See help alter server for more details about altering server parameters.

Field Description
Server Server name
Address Address where the server listens
Port The port on which the server listens
State Server state
Last Event The type of the latest event
Triggered At Time when the latest event was triggered at
Services Services that use this server
Monitors Monitors that monitor this server
Master ID The server ID of the master
Node ID The node ID of this server
Slave Server IDs List of slave server IDs
Statistics Server statistics
Parameters Server parameters

show servers

Usage: show servers

Show detailed information about all servers.

Field Description
Server Server name
Address Address where the server listens
Port The port on which the server listens
State Server state
Last Event The type of the latest event
Triggered At Time when the latest event was triggered at
Services Services that use this server
Monitors Monitors that monitor this server
Master ID The server ID of the master
Node ID The node ID of this server
Slave Server IDs List of slave server IDs
Statistics Server statistics
Parameters Server parameters

show service

Usage: show service <service>

Show detailed information about a service. The Parameters field contains the currently configured parameters for this service. See help alter service for more details about altering service parameters.

Field Description
Service Service name
Router Router that the service uses
State Service state
Started At When the service was started
Current Connections Current connection count
Total Connections Total connection count
Servers Servers that the service uses
Parameters Service parameter
Router Diagnostics Diagnostics provided by the router module

show services

Usage: show services

Show detailed information about all services.

Field Description
Service Service name
Router Router that the service uses
State Service state
Started At When the service was started
Current Connections Current connection count
Total Connections Total connection count
Servers Servers that the service uses
Parameters Service parameter
Router Diagnostics Diagnostics provided by the router module

show monitor

Usage: show monitor <monitor>

Show detailed information about a monitor. The Parameters field contains the currently configured parameters for this monitor. See help alter monitor for more details about altering monitor parameters.

Field Description
Monitor Monitor name
State Monitor state
Servers The servers that this monitor monitors
Parameters Monitor parameters
Monitor Diagnostics Diagnostics provided by the monitor module

show monitors

Usage: show monitors

Show detailed information about all monitors.

Field Description
Monitor Monitor name
State Monitor state
Servers The servers that this monitor monitors
Parameters Monitor parameters
Monitor Diagnostics Diagnostics provided by the monitor module

show session

Usage: show session <session>

Show detailed information about a single session. The list of sessions can be retrieved with the list sessions command. The <session> is the session ID of a particular session.

The Connections field lists the servers to which the session is connected and the Connection IDs field lists the IDs for those connections.

Field Description
Id Session ID
Service The service where the session connected
State Session state
User Username
Host Client host address
Connected Time when the session started
Idle How long the session has been idle, in seconds
Connections Ordered list of backend connections
Connection IDs Thread IDs for the backend connections
Queries Query history
Log Per-session log messages

show sessions

Usage: show sessions

Show detailed information about all sessions. See help show session for more details.

Field Description
Id Session ID
Service The service where the session connected
State Session state
User Username
Host Client host address
Connected Time when the session started
Idle How long the session has been idle, in seconds
Connections Ordered list of backend connections
Connection IDs Thread IDs for the backend connections
Queries Query history
Log Per-session log messages

show filter

Usage: show filter <filter>

The list of services that use this filter is show in the Services field.

Field Description
Filter Filter name
Module The module that the filter uses
Services Services that use the filter
Parameters Filter parameters

show filters

Usage: show filters

Show detailed information of all filters.

Field Description
Filter Filter name
Module The module that the filter uses
Services Services that use the filter
Parameters Filter parameters

show module

Usage: show module <module>

This command shows all available parameters as well as detailed version information of a loaded module.

Field Description
Module Module name
Type Module type
Version Module version
Maturity Module maturity
Description Short description about the module
Parameters All the parameters that the module accepts
Commands Commands that the module provides

show modules

Usage: show modules

Displays detailed information about all modules.

Field Description
Module Module name
Type Module type
Version Module version
Maturity Module maturity
Description Short description about the module
Parameters All the parameters that the module accepts
Commands Commands that the module provides

show maxscale

Usage: show maxscale

See help alter maxscale for more details about altering MaxScale parameters.

Field Description
Version MaxScale version
Commit MaxScale commit ID
Started At Time when MaxScale was started
Activated At Time when MaxScale left passive mode
Uptime Time MaxScale has been running
Parameters Global MaxScale parameters

show thread

Usage: show thread <thread>

Show detailed information about a worker thread.

Field Description
Id Thread ID
Accepts Number of TCP accepts done by this thread
Reads Number of EPOLLIN events
Writes Number of EPOLLOUT events
Hangups Number of EPOLLHUP and EPOLLRDUP events
Errors Number of EPOLLERR events
Avg event queue length Average number of events returned by one epoll_wait call
Max event queue length Maximum number of events returned by one epoll_wait call
Max exec time The longest time spent processing events returned by a epoll_wait call
Max queue time The longest time an event had to wait before it was processed
Current FDs Current number of managed file descriptors
Total FDs Total number of managed file descriptors
Load (1s) Load percentage over the last second
Load (1m) Load percentage over the last minute
Load (1h) Load percentage over the last hour
QC cache size Query classifier size
QC cache inserts Number of times a new query was added into the query classification cache
QC cache hits How many times a query classification was found in the query classification cache
QC cache misses How many times a query classification was not found in the query classification cache
QC cache evictions How many times a query classification result was evicted from the query classification cache

show threads

Usage: show threads

Show detailed information about all worker threads.

Field Description
Id Thread ID
Accepts Number of TCP accepts done by this thread
Reads Number of EPOLLIN events
Writes Number of EPOLLOUT events
Hangups Number of EPOLLHUP and EPOLLRDUP events
Errors Number of EPOLLERR events
Avg event queue length Average number of events returned by one epoll_wait call
Max event queue length Maximum number of events returned by one epoll_wait call
Max exec time The longest time spent processing events returned by a epoll_wait call
Max queue time The longest time an event had to wait before it was processed
Current FDs Current number of managed file descriptors
Total FDs Total number of managed file descriptors
Load (1s) Load percentage over the last second
Load (1m) Load percentage over the last minute
Load (1h) Load percentage over the last hour
QC cache size Query classifier size
QC cache inserts Number of times a new query was added into the query classification cache
QC cache hits How many times a query classification was found in the query classification cache
QC cache misses How many times a query classification was not found in the query classification cache
QC cache evictions How many times a query classification result was evicted from the query classification cache

show logging

Usage: show logging

See help alter logging for more details about altering logging parameters.

Field Description
Current Log File The current log file MaxScale is logging into
Enabled Log Levels List of log levels enabled in MaxScale
Parameters Logging parameters

show commands

Usage: show commands <module>

This command shows the parameters the command expects with the parameter descriptions.

Field Description
Command Command name
Parameters Parameters the command supports
Descriptions Parameter descriptions

set

Usage: set <command>

Commands:
  server <server> <state>  Set server state

Set options:
  --force  Forcefully close all connections to the target server
                                                      [boolean] [default: false]

set server

Usage: set server <server> <state>

If <server> is monitored by a monitor, this command should only be used to set the server into the maintenance state. Any other states will be overridden by the monitor on the next monitoring interval. To manually control server states, use the stop monitor <name> command to stop the monitor before setting the server states manually.

clear

Usage: clear <command>

Commands:
  server <server> <state>  Clear server state

clear server

Usage: clear server <server> <state>

This command clears a server state set by the set server <server> <state> command

drain

Usage: drain <command>

Commands:
  server <server>  Drain a server of connections

Drain options:
  --drain-timeout  Timeout for the drain operation in seconds. If exceeded, the
                   server is added back to all services without putting it into
                   maintenance mode.                      [number] [default: 90]

drain server

Usage: drain server <server>

This command drains the server of connections by first removing it from all services after which it waits until all connections are closed. When all connections are closed, the server is put into the maintenance state and added back to all the services where it was removed from. To take the server back into use, execute clear server <server> maintenance.

enable

Usage: enable <command>

Commands:
  log-priority <log>  Enable log priority [warning|notice|info|debug]
  account <name>      Activate a Linux user account for administrative use

Enable account options:
  --type  Type of user to create
                         [string] [choices: "admin", "basic"] [default: "basic"]

enable log-priority

Usage: enable log-priority <log>

The debug log priority is only available for debug builds of MaxScale.

enable account

Usage: enable account <name>

The Linux user accounts are used by the MaxAdmin UNIX Domain Socket interface

disable

Usage: disable <command>

Commands:
  log-priority <log>  Disable log priority [warning|notice|info|debug]
  account <name>      Disable a Linux user account from administrative use

disable log-priority

Usage: disable log-priority <log>

The debug log priority is only available for debug builds of MaxScale.

disable account

Usage: disable account <name>

The Linux user accounts are used by the MaxAdmin UNIX Domain Socket interface

create

Usage: create <command>

Commands:
  server <name> <host> <port>          Create a new server
  monitor <name> <module> [params...]  Create a new monitor
  service <name> <router> <params...>  Create a new service
  filter <name> <module> [params...]   Create a new filter
  listener <service> <name> <port>     Create a new listener
  user <name> <password>               Create a new network user

Common create options:
  --protocol               Protocol module name                         [string]
  --authenticator          Authenticator module name                    [string]
  --authenticator-options  Option string for the authenticator          [string]
  --tls-key                Path to TLS key                              [string]
  --tls-cert               Path to TLS certificate                      [string]
  --tls-ca-cert            Path to TLS CA certificate                   [string]
  --tls-version            TLS version to use                           [string]
  --tls-cert-verify-depth  TLS certificate verification depth           [string]

Create server options:
  --services  Link the created server to these services                  [array]
  --monitors  Link the created server to these monitors                  [array]

Create monitor options:
  --servers           Link the created service to these servers          [array]
  --monitor-user      Username for the monitor user                     [string]
  --monitor-password  Password for the monitor user                     [string]

Create service options:
  --servers  Link the created service to these servers                   [array]
  --filters  Link the created service to these filters                   [array]

Create listener options:
  --interface  Interface to listen on                   [string] [default: "::"]

Create user options:
  --type  Type of user to create
                         [string] [choices: "admin", "basic"] [default: "basic"]

create server

Usage: create server <name> <host> <port>

The created server will not be used by any services or monitors unless the --services or --monitors options are given. The list of servers a service or a monitor uses can be altered with the link and unlink commands.

create monitor

Usage: create monitor <name> <module> [params...]

The list of servers given with the --servers option should not contain any servers that are already monitored by another monitor. The last argument to this command is a list of key=value parameters given as the monitor parameters.

create service

Usage: service <name> <router> <params...>

The last argument to this command is a list of key=value parameters given as the service parameters. If the --servers or --filters options are used, they must be defined after the service parameters.

Note that the user and password parameters must be defined.

create filter

Usage: filter <name> <module> [params...]

The last argument to this command is a list of key=value parameters given as the filter parameters.

create listener

Usage: create listener <service> <name> <port>

The new listener will be taken into use immediately.

create user

Usage: create user <name> <password>

The created user can be used with the MaxScale REST API as well as the MaxAdmin network interface. By default the created user will have read-only privileges. To make the user an administrative user, use the --type=admin option.

destroy

Usage: destroy <command>

Commands:
  server <name>              Destroy an unused server
  monitor <name>             Destroy an unused monitor
  listener <service> <name>  Destroy an unused listener
  service <name>             Destroy an unused service
  filter <name>              Destroy an unused filter
  user <name>                Remove a network user

destroy server

Usage: destroy server <name>

The server must be unlinked from all services and monitor before it can be destroyed.

destroy monitor

Usage: destroy monitor <name>

The monitor must be unlinked from all servers before it can be destroyed.

destroy listener

Usage: destroy listener <service> <name>

Destroying a listener closes the listening socket, opening it up for reuse.

destroy service

Usage: destroy service <name>

The service must be unlinked from all servers and filters. All listeners for the service must be destroyed before the service itself can be destroyed.

destroy filter

Usage: destroy filter <name>

The filter must not be used by any service when it is destroyed.

destroy user

Usage: destroy user <name>

The last remaining administrative user cannot be removed. Create a replacement administrative user before attempting to remove the last administrative user.

Usage: link <command>

Commands:
  service <name> <server...>  Link servers to a service
  monitor <name> <server...>  Link servers to a monitor

Usage: link service <name> <server...>

This command links servers to a service, making them available for any connections that use the service. Before a server is linked to a service, it should be linked to a monitor so that the server state is up to date. Newly linked server are only available to new connections, existing connections will use the old list of servers.

Usage: link monitor <name> <server...>

Linking a server to a monitor will add it to the list of servers that are monitored by that monitor. A server can be monitored by only one monitor at a time.

Usage: unlink <command>

Commands:
  service <name> <server...>  Unlink servers from a service
  monitor <name> <server...>  Unlink servers from a monitor

Usage: unlink service <name> <server...>

This command unlinks servers from a service, removing them from the list of available servers for that service. New connections to the service will not use the unlinked servers but existing connections can still use the servers.

Usage: unlink monitor <name> <server...>

This command unlinks servers from a monitor, removing them from the list of monitored servers. The servers will be left in their current state when they are unlinked from a monitor.

start

Usage: start <command>

Commands:
  service <name>  Start a service
  monitor <name>  Start a monitor
  services        Start all services                         [aliases: maxscale]

start service

Usage: start service <name>

This starts a service stopped by stop service <name>

start monitor

Usage: start monitor <name>

This starts a monitor stopped by stop monitor <name>

start services

Usage: start [services|maxscale]

This command will execute the start service command for all services in MaxScale.

stop

Usage: stop <command>

Commands:
  service <name>  Stop a service
  monitor <name>  Stop a monitor
  services        Stop all services                          [aliases: maxscale]

stop service

Usage: stop service <name>

Stopping a service will prevent all the listeners for that service from accepting new connections. Existing connections will still be handled normally until they are closed.

stop monitor

Usage: stop monitor <name>

Stopping a monitor will pause the monitoring of the servers. This can be used to manually control server states with the set server command.

stop services

Usage: stop [services|maxscale]

This command will execute the stop service command for all services in MaxScale.

alter

Usage: alter <command>

Commands:
  server <server> <key> <value>           Alter server parameters
  monitor <monitor> <key> <value>         Alter monitor parameters
  service <service> <key> <value>         Alter service parameters
  service-filters <service> [filters...]  Alter filters of a service
  logging <key> <value>                   Alter logging parameters
  maxscale <key> <value>                  Alter MaxScale parameters
  user <name> <password>                  Alter admin user passwords

alter server

Usage: alter server <server> <key> <value>

To display the server parameters, execute show server <server>

alter monitor

Usage: alter monitor <monitor> <key> <value>

To display the monitor parameters, execute show monitor <monitor>

alter service

Usage: alter service <service> <key> <value>

To display the service parameters, execute show service <service>. Some routers support runtime configuration changes to all parameters. Currently all readconnroute, readwritesplit and schemarouter parameters can be changed at runtime. In addition to module specific parameters, the following list of common service parameters can be altered at runtime:

[ "user", "passwd", "enable_root_user", "max_connections", "connection_timeout", "auth_all_servers", "optimize_wildcard", "strip_db_esc", "localhost_match_wildcard_host", "max_slave_connections", "max_slave_replication_lag", "retain_last_statements" ]

alter service-filters

Usage: alter service-filters <service> [filters...]

The order of the filters given as the second parameter will also be the order in which queries pass through the filter chain. If no filters are given, all existing filters are removed from the service.

For example, the command maxctrl alter service filters my-service A B C will set the filter chain for the service my-service so that A gets the query first after which it is passed to B and finally to C. This behavior is the same as if the filters=A|B|C parameter was defined for the service.

alter logging

Usage: alter logging <key> <value>

To display the logging parameters, execute show logging

alter maxscale

Usage: alter maxscale <key> <value>

To display the MaxScale parameters, execute show maxscale. The following list of parameters can be altered at runtime:

[ "auth_connect_timeout", "auth_read_timeout", "auth_write_timeout", "admin_auth", "admin_log_auth_failures", "passive", "ms_timestamp", "skip_permission_checks", "query_retries", "query_retry_timeout", "retain_last_statements", "dump_last_statements" ]

alter user

Usage: alter user <name> <password>

Changes the password for a user. To change the user type, destroy the user and then create it again.

rotate

Usage: rotate <command>

Commands:
  logs  Rotate log files by closing and reopening the files

rotate logs

Usage: rotate logs

This command is intended to be used with the logrotate command.

call

Usage: call <command>

Commands:
  command <module> <command> [params...]  Call a module command

call command

Usage: call command <module> <command> [params...]

To inspect the list of module commands, execute list commands

cluster

Usage: cluster <command>

Commands:
  diff <target>  Show difference between host servers and <target>.
  sync <target>  Synchronize the cluster with target MaxScale server.

cluster diff

Usage: cluster diff <target>

The list of host servers is controlled with the --hosts option. The target server should not be in the host list. Value of <target> must be in HOST:PORT format

cluster sync

Usage: cluster sync <target>

This command will alter all MaxScale instances given in the --hosts option to represent the <target> MaxScale. If the synchronization of a MaxScale instance fails, it will be disabled by executing the stop maxscale command on that instance. Synchronization can be attempted again if a previous attempt failed due to a network failure or some other ephemeral error. Any other errors require manual synchronization of the MaxScale configuration files and a restart of the failed Maxscale.

api

Usage: api <command>

Commands:
  get <resource> [path]  Get raw JSON

API options:
  --sum  Calculate sum of API result. Only works for arrays of numbers e.g. `api
         get --sum servers data[].attributes.statistics.connections`.
                                                      [boolean] [default: false]

api get

Usage: get <resource> [path]

Perform a raw REST API call. The path definition uses JavaScript syntax to extract values. For example, the following command extracts all server states as an array of JSON values: maxctrl api get servers data[].attributes.state

classify

Usage: classify <statement>
Content reproduced on this site is the property of its respective owners, and this content is not reviewed in advance by MariaDB. The views, information and opinions expressed by this content do not necessarily represent those of MariaDB or any other party.