From d480fe97f6bc0e357c1aeab24debd29404c6c035 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Markus=20M=C3=A4kel=C3=A4?= Date: Wed, 6 Sep 2017 10:59:08 +0300 Subject: [PATCH] MXS-1390: Update MaxCtrl documentation Updated documentation generation script and regenerated documentation. Now all command documentation is generated by using the output of the `help` commands. --- Documentation/Reference/MaxCtrl.md | 418 +++++++++++++++++++++++++++-- maxctrl/autodoc.sh | 24 +- 2 files changed, 419 insertions(+), 23 deletions(-) diff --git a/Documentation/Reference/MaxCtrl.md b/Documentation/Reference/MaxCtrl.md index 6fc92d613..219ea5a69 100644 --- a/Documentation/Reference/MaxCtrl.md +++ b/Documentation/Reference/MaxCtrl.md @@ -33,7 +33,7 @@ For more information about the MaxScale REST API, refer to the * [call](#call) * [cluster](#cluster) -# Options +## Options All command accept the following global options. @@ -53,7 +53,7 @@ Options: --help Show help [boolean] ``` -### `list` +## list ``` Usage: list @@ -71,7 +71,61 @@ Commands: ``` -### `show` +### list servers + +Usage: `maxctrl.js list servers` + +List all servers in MaxScale. + +### list services + +Usage: `maxctrl.js list services` + +List all services and the servers they use. + +### list listeners + +Usage: `maxctrl.js list listeners ` + +List listeners for a service. + +### list monitors + +Usage: `maxctrl.js list monitors` + +List all monitors in MaxScale. + +### list sessions + +Usage: `maxctrl.js list sessions` + +List all client sessions. + +### list filters + +Usage: `maxctrl.js list filters` + +List all filters in MaxScale. + +### list modules + +Usage: `maxctrl.js list modules` + +List all currently loaded modules. + +### list users + +Usage: `maxctrl.js list users` + +List the users that can be used to connect to the MaxScale REST API. + +### list commands + +Usage: `maxctrl.js list commands` + +List all available module commands. + +## show ``` Usage: show @@ -89,7 +143,71 @@ Commands: ``` -### `set` +### show server + +Usage: `maxctrl.js 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. + +### show service + +Usage: `maxctrl.js 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. + +### show monitor + +Usage: `maxctrl.js 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. + +### show session + +Usage: `maxctrl.js 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. + +### show filter + +Usage: `maxctrl.js show filter ` + +The list of services that use this filter is show in the `Services` field. + +### show module + +Usage: `maxctrl.js show module ` + +This command shows all available parameters as well as detailed version +information of a loaded module. + +### show maxscale + +Usage: `maxctrl.js show maxscale` + +See `help alter maxscale` for more details about altering MaxScale parameters. + +### show logging + +Usage: `maxctrl.js show logging` + +See `help alter logging` for more details about altering logging parameters. + +### show commands + +Usage: `maxctrl.js show commands ` + +This command shows the parameters the command expects with the parameter +descriptions. + +## set ``` Usage: set @@ -99,7 +217,17 @@ Commands: ``` -### `clear` +### set server + +Usage: `maxctrl.js 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 @@ -109,7 +237,14 @@ Commands: ``` -### `enable` +### clear server + +Usage: `maxctrl.js clear server ` + +This command clears a server state set by the `set server ` +command + +## enable ``` Usage: enable @@ -124,7 +259,19 @@ Enable account options: ``` -### `disable` +### enable log-priority + +Usage: `maxctrl.js enable log-priority ` + +The `debug` log priority is only available for debug builds of MaxScale. + +### enable account + +Usage: `maxctrl.js enable account ` + +The Linux user accounts are used by the MaxAdmin UNIX Domain Socket interface + +## disable ``` Usage: disable @@ -135,7 +282,19 @@ Commands: ``` -### `create` +### disable log-priority + +Usage: `maxctrl.js disable log-priority ` + +The `debug` log priority is only available for debug builds of MaxScale. + +### disable account + +Usage: `maxctrl.js disable account ` + +The Linux user accounts are used by the MaxAdmin UNIX Domain Socket interface + +## create ``` Usage: create @@ -174,7 +333,37 @@ Create user options: ``` -### `destroy` +### create server + +Usage: `maxctrl.js create server ` + +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: `maxctrl.js create monitor ` + +The list of servers given with the --servers option should not contain any +servers that are already monitored by another monitor. + +### create listener + +Usage: `maxctrl.js create listener ` + +The new listener will be taken into use immediately. + +### create user + +Usage: `maxctrl.js 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 administrative +privileges. To limit the user to read-only operations, use the `--type=basic` +option. + +## destroy ``` Usage: destroy @@ -187,7 +376,36 @@ Commands: ``` -### `link` +### destroy server + +Usage: `maxctrl.js destroy server ` + +The server must be unlinked from all services and monitor before it can be +destroyed. + +### destroy monitor + +Usage: `maxctrl.js destroy monitor ` + +The monitor must be unlinked from all servers before it can be destroyed. + +### destroy listener + +Usage: `maxctrl.js destroy listener ` + +Destroying a monitor causes it to be removed on the next restart. Destroying a +listener at runtime stops it from accepting new connections but it will still be +bound to the listening socket. This means that new listeners cannot be created +to replace destroyed listeners without restarting MaxScale. + +### destroy user + +Usage: `maxctrl.js 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 @@ -198,7 +416,25 @@ Commands: ``` -### `unlink` +### link service + +Usage: `maxctrl.js 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: `maxctrl.js 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 @@ -209,7 +445,23 @@ Commands: ``` -### `start` +### unlink service + +Usage: `maxctrl.js 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: `maxctrl.js 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 @@ -221,7 +473,26 @@ Commands: ``` -### `stop` +### start service + +Usage: `maxctrl.js start service ` + +This starts a service stopped by `stop service ` + +### start monitor + +Usage: `maxctrl.js start monitor ` + +This starts a monitor stopped by `stop monitor ` + +### start maxscale + +Usage: `maxctrl.js start maxscale` + +This command will execute the `start service` command for all services in +MaxScale. + +## stop ``` Usage: stop @@ -233,7 +504,29 @@ Commands: ``` -### `alter` +### stop service + +Usage: `maxctrl.js 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: `maxctrl.js 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 maxscale + +Usage: `maxctrl.js stop maxscale` + +This command will execute the `stop service` command for all services in +MaxScale. + +## alter ``` Usage: alter @@ -247,7 +540,60 @@ Commands: ``` -### `rotate` +### alter server + +Usage: `maxctrl.js alter server ` + +To display the server parameters, execute `show server ` + +### alter monitor + +Usage: `maxctrl.js alter monitor ` + +To display the monitor parameters, execute `show monitor ` + +### alter service + +Usage: `maxctrl.js alter service ` + +To display the service parameters, execute `show service `. The +following list of 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" +] + +### alter logging + +Usage: `maxctrl.js alter logging ` + +To display the logging parameters, execute `show logging` + +### alter maxscale + +Usage: `maxctrl.js 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" +] + +## rotate ``` Usage: rotate @@ -257,26 +603,56 @@ Commands: ``` -### `call` +### rotate logs + +Usage: `maxctrl.js rotate logs` + +This command is intended to be used with the `logrotate` command. + +## call ``` Usage: call Commands: - command Call a module command - [parameters...] + command [params...] Call a module command ``` -### `cluster` +### call command + +Usage: `maxctrl.js call command [params...]` + +To inspect the list of module commands, execute `list commands` + +## cluster ``` Usage: cluster Commands: - diff Show difference between host servers and . Value must - be in HOST:PORT format + diff Show difference between host servers and . sync Synchronize the cluster with target MaxScale server. ``` +### cluster diff + +Usage: `maxctrl.js 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: `maxctrl.js cluster sync ` + +This command will alter all MaxScale instances given in the --hosts option to +represent the 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. + diff --git a/maxctrl/autodoc.sh b/maxctrl/autodoc.sh index 4896d4b0d..d14d5886f 100755 --- a/maxctrl/autodoc.sh +++ b/maxctrl/autodoc.sh @@ -9,12 +9,32 @@ done) COMMANDS=$(for i in $ITEMS do - echo "### \`$i\`" + echo "## $i" echo echo "\`\`\`" node maxctrl.js help $i|awk 'BEGIN{p=1} /Global Options:/{p=0}{if(p){print $0}}' echo "\`\`\`" echo + + CMD=`node maxctrl.js help $i|awk '/^$/{p=0} {if(p){print $1}}/Commands:/{p=1}'` + + for j in $CMD + do + echo "### $i $j" + echo + USAGE=`node maxctrl.js help $i $j|head -n 1` + echo "Usage: \`$USAGE\`" + echo "" + + # Print the detailed command explanation if it has one + DESC=`node maxctrl.js help $i $j|sed 's/[\`]/\\\`/'|awk 'BEGIN{p=2} /Options:/{p=0}{if(p==1){print $0}}/^$/{if(!p){p=1}}'` + if [ ! -z "$DESC" ] + then + echo "$DESC" + echo + fi + + done done) GLOBALOPTS=$(node maxctrl.js help $i|awk '{if(p){print $0}} /Global Options:/{p=1}') @@ -40,7 +60,7 @@ For more information about the MaxScale REST API, refer to the $TOC -# Options +## Options All command accept the following global options.