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

Add documentation for runtime config changes

Browse Source 
The MaxAdmin document now lists and describes the new runtime
configuration change commands.
This commit is contained in:
Markus Makela
2016-12-13 23:06:36 +02:00
committed by Markus Mäkelä
parent 916320cf67
commit 04d5eaf5f3
1 changed files with 285 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

310
Documentation/Reference/MaxAdmin.md
View File

@ -15,6 +15,10 @@
- [Working with Monitors](#working-with-monitors) - [Working with Monitors](#working-with-monitors)
- [MariaDB MaxScale Status Commands](#maxscale-status-commands) - [MariaDB MaxScale Status Commands](#maxscale-status-commands)
- [Administration Commands](#administration-commands) - [Administration Commands](#administration-commands)
- [Runtime Configuration Changes](#runtime-configuration-changes)
- [Servers](#servers)
- [Listeners](#listeners)
- [Monitors](#monitors)
- [Tuning MariaDB MaxScale](#tuning-mariadb-maxscale) - [Tuning MariaDB MaxScale](#tuning-mariadb-maxscale)
# Overview # Overview
@ -276,7 +280,7 @@ be given in this line. For example to create a script file that runs a set of
list commands list commands
``` ```
#!/usr/local/bin/maxadmin #!/usr/bin/maxadmin
list modules list modules
list servers list servers
list services list services
@ -328,40 +332,84 @@ the command help.
``` ```
MaxScale> help MaxScale> help
Available commands: Available commands:
add user add [user|server]
remove [user|server]
create [server|listener|monitor]
destroy [server|listener|monitor]
alter [server|monitor]
set [server|pollsleep|nbpolls|log_throttling]
clear server clear server
disable [heartbeat|log|root] disable [heartbeat|log|log-priority|sessionlog|sessionlog-priority|root|feedback|syslog|maxlog|account]
enable [heartbeat|log|root] enable [heartbeat|log|log-priority|sessionlog|sessionlog-priority|root|feedback|syslog|maxlog|account]
list [clients|dcbs|filters|listeners|modules|monitors|services|servers|sessions] flush [log|logs]
list [clients|dcbs|filters|listeners|modules|monitors|services|servers|sessions|threads|commands]
reload [config|dbusers] reload [config|dbusers]
remove user restart [monitor|service|listener]
restart [monitor|service] shutdown [maxscale|monitor|service|listener]
set server show [dcblist|dcbs|dcb|dbusers|epoll|eventq|eventstats|feedbackreport|filter|filters|log_throttling|modules|monitor|monitors|persistent|server|servers|serversjson|services|service|session|sessionlist|sessions|tasks|threads|users]
show [dcbs|dcb|dbusers|epoll|filter|filters|modules|monitor|monitors|server|servers|services|service|session|sessions|users] sync logs
shutdown [maxscale|monitor|service] call command
Type help command to see details of each command. Where commands require names
as arguments and these names contain whitespace either the \ character may be
used to escape the whitespace or the name may be enclosed in double quotes ".
Type help command to see details of each command.
Where commands require names as arguments and these names contain
whitespace either the \ character may be used to escape the whitespace
or the name may be enclosed in double quotes ".
MaxScale> MaxScale>
``` ```
To see more detail on a particular command, and a list of the sub commands of To see more details on a particular command, and a list of the sub commands of
the command, type help followed by the command name. the command, type help followed by the command name.
``` ```
MaxScale> help list MaxScale> help list
Available options to the list command: Available options to the list command:
clients List all the client connections to MaxScale 'clients' - List all clients
dcbs List all the DCBs active within MaxScale
filters List all the filters defined within MaxScale List all the client connections to MaxScale
listeners List all the listeners defined within MaxScale
modules List all currently loaded modules 'dcbs' - List all DCBs
monitors List all monitors
services List all the services defined within MaxScale List all the DCBs active within MaxScale
servers List all the servers defined within MaxScale
sessions List all the active sessions within MaxScale 'filters' - List all filters
List all the filters defined within MaxScale
'listeners' - List all listeners
List all the listeners defined within MaxScale
'modules' - List all currently loaded modules
List all currently loaded modules
'monitors' - List all monitors
List all monitors
'services' - List all the services
List all the services defined within MaxScale
'servers' - List all servers
List all the servers defined within MaxScale
'sessions' - List all sessions
List all the active sessions within MaxScale
'threads' - List polling threads
List the status of the polling threads in MaxScale
'commands' - List registered commands
Usage list commands [DOMAIN] [COMMAND]
Parameters:
DOMAIN Regular expressions for filtering module domains
COMMAND Regular expressions for filtering module commands
MaxScale> MaxScale>
``` ```
@ -1154,13 +1202,225 @@ of the values to 0, disables the throttling.
## Reloading The Configuration ## Reloading The Configuration
A command, _reload config_, is available that will cause MariaDB MaxScale to A command, _reload config_, is available that will cause MariaDB MaxScale to
reload the maxscale.cnf configuration file. reload the maxscale.cnf configuration file. Refer to the [Configuration Guide](../Getting-Started/Configuration-Guide.md)
for a list of parameters that can be changed with it.
## Shutting Down MariaDB MaxScale ## Shutting Down MariaDB MaxScale
The MariaDB MaxScale server may be shutdown using the _shutdown maxscale_ The MariaDB MaxScale server may be shutdown using the _shutdown maxscale_
command. command.
# Runtime Configuration Changes
Starting with the 2.1 version of MaxScale, you can modify the runtime
configuration.
## Servers
### Creating a New Server
In order to add new servers into MaxScale, they must first be created. They can
be created with the `create server` command. Any runtime configuration changes
to servers are persisted meaning that they will still be in effect even after a
restart.
```
'server' - Create a new server
Usage: create server NAME HOST [PORT] [PROTOCOL] [AUTHENTICATOR] [OPTIONS]
Create a new server from the following parameters.
NAME Server name
HOST Server host address
PORT Server port (default 3306)
PROTOCOL Server protocol (default MySQLBackend)
AUTHENTICATOR Authenticator module name (default MySQLAuth)
OPTIONS Options for the authenticator module
The first three parameters are required, the others are optional.
```
### Adding Servers to Services and Monitors
To add a server to a service or a monitor, use the `add server` command. Any
changes to the servers of a service or a monitor are persisted meaning that they
will still be in effect even after a restart.
Servers added to services will only be taken into use by new sessions. Old
sessions will only use the servers that were a part of the service when they
were created.
```
'server' - Add a new server to a service
Usage: add server SERVER TARGET...
The TARGET must be a list of service and monitor names
e.g. add server my-db my-service 'Cluster Monitor'
A server can be assigned to a maximum of 11 objects in one command
```
### Removing Servers from Services and Monitors
To remove servers from a service or a monitor, use the `remove server`
command. The same rules about server usage for services that apply to `add
server` also apply to `remove server`. The servers will only be removed from new
sessions created after the command is executed.
```
'server' - Remove a server from a service or a monitor
Usage: remove server SERVER TARGET...
The TARGET must be a list of service and monitor names
e.g. remove server my-db my-service 'Cluster Monitor'
A server can be removed from a maximum of 11 objects in one command
```
### Altering Servers
You can alter server parameters with the `alter server` command. Any changes to
the address or port of the server will take effect for new connections
only. Changes to other parameters will take effect immediately.
Please note that in order for SSL to be enabled for a created server, all of the
required SSL parameters (`ssl`, `ssl_key`, `ssl_cert` and `ssl_ca_cert`) must be
given in the same command.
```
Usage: alter server NAME KEY=VALUE ...
This will alter an existing parameter of a server. The accepted values for KEY are:
address Server address
port Server port
monuser Monitor user for this server
monpw Monitor password for this server
ssl Enable SSL, value must be 'required'
ssl_key Path to SSL private key
ssl_cert Path to SSL certificate
ssl_ca_cert Path to SSL CA certificate
ssl_version SSL version
ssl_cert_verify_depth Certificate verification depth
A maximum of 11 parameters can be changed at one time.
To configure SSL for a newly created server, the 'ssl', 'ssl_cert',
'ssl_key' and 'ssl_ca_cert' parameters must be given at the same time.
```
### Destroying Servers
You can destroy created servers with the `destroy server` command. Only servers
created with the `create server` command should be destroyed. A server can only
be destroyed once it has been removed from all services and monitors.
```
'server' - Destroy a server
Usage: destroy server NAME
```
## Listeners
### Creating New Listeners
To create a new listener for a service, use the `create listener` command. This
will create and start a new listener for a service which will immediately start
listening for new connections on the specified port.
Please note that in order for SSL to be enabled for a created listeners, all of
the required SSL parameters (`ssl`, `ssl_key`, `ssl_cert` and `ssl_ca_cert`)
must be given. All the `create listener` parameters do not need to be defined in
order for SSL to be enabled. The _default_ parameter can be used to signal that
MaxScale should use a default value for the parameter in question.
```
'listener' - Create a new listener for a service
Usage: create listener SERVICE NAME [HOST] [PORT] [PROTOCOL] [AUTHENTICATOR] [OPTIONS]
[SSL_KEY] [SSL_CERT] [SSL_CA] [SSL_VERSION] [SSL_VERIFY_DEPTH]
Create a new server from the following parameters.
SERVICE Service where this listener is added
NAME Listener name
HOST Listener host address (default 0.0.0.0)
PORT Listener port (default 3306)
PROTOCOL Listener protocol (default MySQLClient)
AUTHENTICATOR Authenticator module name (default MySQLAuth)
OPTIONS Options for the authenticator module
SSL_KEY Path to SSL private key
SSL_CERT Path to SSL certificate
SSL_CA Path to CA certificate
SSL_VERSION SSL version (default MAX)
SSL_VERIFY_DEPTH Certificate verification depth
The first two parameters are required, the others are optional.
Any of the optional parameters can also have the value 'default'
which will be replaced with the default value.
```
### Destroying Listeners
You can destroy created listeners with the `destroy listener` command. This will
remove the persisted configuration and it will not be created on the next
startup. The listener is stopped but it will remain a part of the runtime
configuration until the next restart.
```
'listener' - Destroy a listener
Usage: destroy listener SERVICE NAME
```
## Monitors
### Creating New Monitors
The `create monitor` command creates a new monitor that is initially
stopped. Configure the monitor with the `alter monitor` command and then start
it with the `restart monitor` command. The _user_ and _password_ parameters of
the monitor must be defined before the monitor is started.
```
'monitor' - Create a new monitor
Usage: create monitor NAME MODULE
NAME Monitor name
MODULE Monitor module
```
### Altering Monitors
To alter a monitor, use the `alter monitor` command. Module specific parameters
can also be altered.
```
'monitor' - Alter monitor parameters
Usage: alter monitor NAME KEY=VALUE ...
This will alter an existing parameter of a monitor. To remove parameters,
pass an empty value for a key e.g. 'maxadmin alter monitor my-monitor my-key='
A maximum of 11 key-value pairs can be changed at one time
```
### Destroying Monitors
To destroy a monitor, use the `destroy monitor` command. All servers need to be
removed from the monitor before it can be destroyed. Only created monitors
should be destroyed and they will remain a part of the runtime configuration
until the next restart.
```
'monitor' - Destroy a monitor
Usage: destroy monitor NAME
```
# Tuning MariaDB MaxScale # Tuning MariaDB MaxScale
The way that MariaDB MaxScale does it’s polling is that each of the polling The way that MariaDB MaxScale does it’s polling is that each of the polling