hcq/MaxScale
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

MXS-1390: Update MaxCtrl documentation

Browse Source 
Updated documentation generation script and regenerated documentation. Now
all command documentation is generated by using the output of the `help`
commands.
This commit is contained in:
Markus Mäkelä
2017-09-06 10:59:08 +03:00
parent c8490df566
commit d480fe97f6
2 changed files with 419 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

418
Documentation/Reference/MaxCtrl.md
View File

@ -33,7 +33,7 @@ For more information about the MaxScale REST API, refer to the
* [call](#call) * [call](#call)
* [cluster](#cluster) * [cluster](#cluster)
# Options ## Options
All command accept the following global options. All command accept the following global options.
@ -53,7 +53,7 @@ Options:
--help Show help [boolean] --help Show help [boolean]
``` ```
### `list` ## list
``` ```
Usage: list <command> Usage: list <command>
@ -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 <service>`
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 <command> Usage: show <command>
@ -89,7 +143,71 @@ Commands:
``` ```
### `set` ### show server
Usage: `maxctrl.js 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.
### show service
Usage: `maxctrl.js 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.
### show monitor
Usage: `maxctrl.js 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.
### show session
Usage: `maxctrl.js 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.
### show filter
Usage: `maxctrl.js show filter <filter>`
The list of services that use this filter is show in the `Services` field.
### show module
Usage: `maxctrl.js show module <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 <module>`
This command shows the parameters the command expects with the parameter
descriptions.
## set
``` ```
Usage: set <command> Usage: set <command>
@ -99,7 +217,17 @@ Commands:
``` ```
### `clear` ### set server
Usage: `maxctrl.js 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> Usage: clear <command>
@ -109,7 +237,14 @@ Commands:
``` ```
### `enable` ### clear server
Usage: `maxctrl.js clear server <server> <state>`
This command clears a server state set by the `set server <server> <state>`
command
## enable
``` ```
Usage: enable <command> Usage: enable <command>
@ -124,7 +259,19 @@ Enable account options:
``` ```
### `disable` ### enable log-priority
Usage: `maxctrl.js enable log-priority <log>`
The `debug` log priority is only available for debug builds of MaxScale.
### enable account
Usage: `maxctrl.js enable account <name>`
The Linux user accounts are used by the MaxAdmin UNIX Domain Socket interface
## disable
``` ```
Usage: disable <command> Usage: disable <command>
@ -135,7 +282,19 @@ Commands:
``` ```
### `create` ### disable log-priority
Usage: `maxctrl.js disable log-priority <log>`
The `debug` log priority is only available for debug builds of MaxScale.
### disable account
Usage: `maxctrl.js disable account <name>`
The Linux user accounts are used by the MaxAdmin UNIX Domain Socket interface
## create
``` ```
Usage: create <command> Usage: create <command>
@ -174,7 +333,37 @@ Create user options:
``` ```
### `destroy` ### create server
Usage: `maxctrl.js 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: `maxctrl.js create monitor <name> <module>`
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 <service> <name> <port>`
The new listener will be taken into use immediately.
### create user
Usage: `maxctrl.js 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 administrative
privileges. To limit the user to read-only operations, use the `--type=basic`
option.
## destroy
``` ```
Usage: destroy <command> Usage: destroy <command>
@ -187,7 +376,36 @@ Commands:
``` ```
### `link` ### destroy server
Usage: `maxctrl.js destroy server <name>`
The server must be unlinked from all services and monitor before it can be
destroyed.
### destroy monitor
Usage: `maxctrl.js destroy monitor <name>`
The monitor must be unlinked from all servers before it can be destroyed.
### destroy listener
Usage: `maxctrl.js destroy listener <service> <name>`
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 <name>`
The last remaining administrative user cannot be removed. Create a replacement
administrative user before attempting to remove the last administrative user.
## link
``` ```
Usage: link <command> Usage: link <command>
@ -198,7 +416,25 @@ Commands:
``` ```
### `unlink` ### link service
Usage: `maxctrl.js 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.
### link monitor
Usage: `maxctrl.js 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.
## unlink
``` ```
Usage: unlink <command> Usage: unlink <command>
@ -209,7 +445,23 @@ Commands:
``` ```
### `start` ### unlink service
Usage: `maxctrl.js 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.
### unlink monitor
Usage: `maxctrl.js 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> Usage: start <command>
@ -221,7 +473,26 @@ Commands:
``` ```
### `stop` ### start service
Usage: `maxctrl.js start service <name>`
This starts a service stopped by `stop service <name>`
### start monitor
Usage: `maxctrl.js start monitor <name>`
This starts a monitor stopped by `stop monitor <name>`
### start maxscale
Usage: `maxctrl.js start maxscale`
This command will execute the `start service` command for all services in
MaxScale.
## stop
``` ```
Usage: stop <command> Usage: stop <command>
@ -233,7 +504,29 @@ Commands:
``` ```
### `alter` ### stop service
Usage: `maxctrl.js 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: `maxctrl.js 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 maxscale
Usage: `maxctrl.js stop maxscale`
This command will execute the `stop service` command for all services in
MaxScale.
## alter
``` ```
Usage: alter <command> Usage: alter <command>
@ -247,7 +540,60 @@ Commands:
``` ```
### `rotate` ### alter server
Usage: `maxctrl.js alter server <server> <key> <value>`
To display the server parameters, execute `show server <server>`
### alter monitor
Usage: `maxctrl.js alter monitor <monitor> <key> <value>`
To display the monitor parameters, execute `show monitor <monitor>`
### alter service
Usage: `maxctrl.js alter service <service> <key> <value>`
To display the service parameters, execute `show service <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 <key> <value>`
To display the logging parameters, execute `show logging`
### alter maxscale
Usage: `maxctrl.js 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"
]
## rotate
``` ```
Usage: rotate <command> Usage: rotate <command>
@ -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 <command> Usage: call <command>
Commands: Commands:
command <module> <command> Call a module command command <module> <command> [params...] Call a module command
[parameters...]
``` ```
### `cluster` ### call command
Usage: `maxctrl.js call command <module> <command> [params...]`
To inspect the list of module commands, execute `list commands`
## cluster
``` ```
Usage: cluster <command> Usage: cluster <command>
Commands: Commands:
diff <target> Show difference between host servers and <target>. Value must diff <target> Show difference between host servers and <target>.
be in HOST:PORT format
sync <target> Synchronize the cluster with target MaxScale server. sync <target> Synchronize the cluster with target MaxScale server.
``` ```
### cluster diff
Usage: `maxctrl.js 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: `maxctrl.js 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.

24
maxctrl/autodoc.sh
View File

@ -9,12 +9,32 @@ done)
COMMANDS=$(for i in $ITEMS COMMANDS=$(for i in $ITEMS
do do
echo "### \`$i\`" echo "## $i"
echo echo
echo "\`\`\`" echo "\`\`\`"
node maxctrl.js help $i|awk 'BEGIN{p=1} /Global Options:/{p=0}{if(p){print $0}}' node maxctrl.js help $i|awk 'BEGIN{p=1} /Global Options:/{p=0}{if(p){print $0}}'
echo "\`\`\`" echo "\`\`\`"
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) done)
GLOBALOPTS=$(node maxctrl.js help $i|awk '{if(p){print $0}} /Global Options:/{p=1}') 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 $TOC
# Options ## Options
All command accept the following global options. All command accept the following global options.