# 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](../REST-API/API.md) and the [Configuration Guide](../Getting-Started/Configuration-Guide.md). # Commands * [list](#list) * [show](#show) * [set](#set) * [clear](#clear) * [drain](#drain) * [enable](#enable) * [disable](#disable) * [create](#create) * [destroy](#destroy) * [link](#link) * [unlink](#unlink) * [start](#start) * [stop](#stop) * [alter](#alter) * [rotate](#rotate) * [reload](#reload) * [call](#call) * [cluster](#cluster) * [api](#api) * [classify](#classify) ## 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. Ignored while in interactive mode. [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 Commands: servers List servers services List services listeners 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 ` 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 Commands: server Show server servers Show all servers service Show service services Show all services monitor Show monitor monitors Show all monitors session Show session sessions Show all sessions filter Show filter filters Show all filters module Show loaded module modules Show all loaded modules maxscale Show MaxScale information thread Show thread threads Show all threads logging Show MaxScale logging information commands Show module commands of a module qc_cache Show query classifier cache dbusers Show database users of the service ``` ### show server `Usage: show 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 Version | Server version 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 Version | Server version 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 ` 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 Filters | Filters 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 Filters | Filters that the service uses Parameters | Service parameter Router Diagnostics | Diagnostics provided by the router module ### show monitor `Usage: show 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 ` Show detailed information about a single session. The list of sessions can be retrieved with the `list sessions` command. The 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 ` 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 ` 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 ` 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 ` 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 ### show qc_cache `Usage: show qc_cache` Show contents (statement and hits) of query classifier cache. ### show dbusers `Usage: show dbusers ` Show information about the database users of the service ## set ``` Usage: set Commands: server Set server state Set options: --force Forcefully close all connections to the target server [boolean] [default: false] ``` ### set server `Usage: set server ` If 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 ` command to stop the monitor before setting the server states manually. ## clear ``` Usage: clear Commands: server Clear server state ``` ### clear server `Usage: clear server ` This command clears a server state set by the `set server ` command ## drain ``` Usage: drain Commands: 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 ` 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 maintenance`. ## enable ``` Usage: enable Commands: log-priority Enable log priority [warning|notice|info|debug] account 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 ` The `debug` log priority is only available for debug builds of MaxScale. ### enable account `Usage: enable account ` The Linux user accounts are used by the MaxAdmin UNIX Domain Socket interface ## disable ``` Usage: disable Commands: log-priority Disable log priority [warning|notice|info|debug] account Disable a Linux user account from administrative use ``` ### disable log-priority `Usage: disable log-priority ` The `debug` log priority is only available for debug builds of MaxScale. ### disable account `Usage: disable account ` The Linux user accounts are used by the MaxAdmin UNIX Domain Socket interface ## create ``` Usage: create Commands: server [port] Create a new server monitor [params...] Create a new monitor service Create a new service filter [params...] Create a new filter listener Create a new listener user Create a new network user ``` ### create server `Usage: create server [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. If the argument is an absolute path, the server will use a local UNIX domain socket connection. In this case the [port] argument is ignored. ### create monitor `Usage: create monitor [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 ` 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 [params...]` The last argument to this command is a list of key=value parameters given as the filter parameters. ### create listener `Usage: create listener ` The new listener will be taken into use immediately. ### create user `Usage: create user ` 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. Basic users can only perform `list` and `show` commands. ## destroy ``` Usage: destroy Commands: server Destroy an unused server monitor Destroy an unused monitor listener Destroy an unused listener service Destroy an unused service filter Destroy an unused filter user Remove a network user ``` ### destroy server `Usage: destroy server ` The server must be unlinked from all services and monitor before it can be destroyed. ### destroy monitor `Usage: destroy monitor ` The monitor must be unlinked from all servers before it can be destroyed. ### destroy listener `Usage: destroy listener ` Destroying a listener closes the listening socket, opening it up for reuse. ### destroy service `Usage: destroy service ` 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 ` The filter must not be used by any service when it is destroyed. ### destroy user `Usage: destroy user ` The last remaining administrative user cannot be removed. Create a replacement administrative user before attempting to remove the last administrative user. ## link ``` Usage: link Commands: service Link servers to a service monitor Link servers to a monitor ``` ### link service `Usage: link service ` 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. ### link monitor `Usage: link monitor ` 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. ## unlink ``` Usage: unlink Commands: service Unlink servers from a service monitor Unlink servers from a monitor ``` ### unlink service `Usage: unlink service ` 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. ### unlink monitor `Usage: unlink monitor ` 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 Commands: service Start a service monitor Start a monitor services Start all services [aliases: maxscale] ``` ### start service `Usage: start service ` This starts a service stopped by `stop service ` ### start monitor `Usage: start monitor ` This starts a monitor stopped by `stop monitor ` ### start services `Usage: start [services|maxscale]` This command will execute the `start service` command for all services in MaxScale. ## stop ``` Usage: stop Commands: service Stop a service monitor Stop a monitor services Stop all services [aliases: maxscale] ``` ### stop service `Usage: stop service ` 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 ` 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 Commands: server Alter server parameters [params...] monitor Alter monitor parameters [params...] service Alter service parameters [params...] service-filters [filters...] Alter filters of a service logging [params...] Alter logging parameters maxscale [params...] Alter MaxScale parameters user Alter admin user passwords ``` ### alter server `Usage: alter server ...` To display the server parameters, execute `show server `. ### alter [params...] `Usage: alter ` Multiple values can be updated at a time by providing the parameter name followed by the new value. For example, the following command would change both the `address` and the `port` parameter of a server: alter server server1 address 127.0.0.1 port 3306 All alter commands except `alter user` and `alter service-filters` support multiple parameters. ### alter monitor `Usage: alter monitor ...` To display the monitor parameters, execute `show monitor ` ### alter [params...] `Usage: alter ` Multiple values can be updated at a time by providing the parameter name followed by the new value. For example, the following command would change both the `address` and the `port` parameter of a server: alter server server1 address 127.0.0.1 port 3306 All alter commands except `alter user` and `alter service-filters` support multiple parameters. ### alter service `Usage: alter service ...` To display the service parameters, execute `show 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 [params...] `Usage: alter ` Multiple values can be updated at a time by providing the parameter name followed by the new value. For example, the following command would change both the `address` and the `port` parameter of a server: alter server server1 address 127.0.0.1 port 3306 All alter commands except `alter user` and `alter service-filters` support multiple parameters. ### alter service-filters `Usage: alter service-filters [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 ...` To display the logging parameters, execute `show logging` ### alter maxscale `Usage: alter maxscale ...` 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 ` Changes the password for a user. To change the user type, destroy the user and then create it again. ## rotate ``` Usage: rotate 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. ## reload ``` Usage: reload Commands: service Reloads the database users of this service ``` ### reload service `Usage: reload service ` ## call ``` Usage: call Commands: command [params...] Call a module command ``` ### call command `Usage: call command [params...]` To inspect the list of module commands, execute `list commands` ## cluster ``` Usage: cluster Commands: diff Show difference between host servers and . sync Synchronize the cluster with target MaxScale server. ``` ### cluster diff `Usage: cluster diff ` The list of host servers is controlled with the --hosts option. The target server should not be in the host list. Value of must be in HOST:PORT format ### cluster sync `Usage: cluster sync ` This command will alter all MaxScale instances given in the --hosts option to represent the MaxScale. Value of must be in HOST:PORT format. 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. Note: New objects created by `cluster sync` will have a placeholder value and must be manually updated. Passwords for existing objects will not be updated by `cluster sync` and must also be manually updated. ## api ``` Usage: api Commands: get [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 [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 ```