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

Allow socket and address/port to be used with maxadmin

Browse Source 
It's now possible to use both a Unix domain socket and host/port
when connecting with MaxAdmin to MaxScale.

By default MaxAdmin will attempt to use the default Unix domain
socket, but if host and/or port has been specified, then an inet
socket will be used.

maxscaled will authenticate the connection attempt differently
depending on whether a Unix domain socket is used or not. If
a Unix domain socket is used, then the Linux user id will be
used for the authorization, otherwise the 1.4.3 username/password
handshake will be performed.

adminusers has now been extended so that there is one set of
functions for local users (connecting locally over a Unix socket)
and one set of functions for remote users (connecting locally
or remotely over an Inet socket).

The local users are stored in the new .../maxscale-users and the
remote users in .../passwd. That is, the old users of a 1.4
installation will work as such in 2.0.

One difference is that there will be *no* default remote user.
That is, remote users will always have to be added manually using
a local user.

The implementation is shared; the local and remote alternatives
use common functions to which the hashtable and filename to be
used are forwarded.

The commands "[add|remove] user" behave now exactly like they did
in 1.4.3, and also all existing users work out of the box.

In addition there is now the commands "[enable|disable] account"
using which Linux accounts can be enabled for MaxAdmin usage.
This commit is contained in:
Johan Wikman
2016-08-30 14:33:00 +03:00
parent d337aa0476
commit a9b0a5550c
20 changed files with 1175 additions and 451 deletions
Download Patch File Download Diff File Expand all files Collapse all files

176
Documentation/Reference/MaxAdmin.md
View File

@ -3,6 +3,7 @@
# The Maxscale Administrative & Monitoring Client Application
- [Overview](#overview)
- [Configuring MariaDB MaxScale for MaxAdmin](#configuring)
- [Running MaxAdmin](#running)
- [Working With Administration Interface Users](#interface)
- [Getting Help](#help)
@ -14,7 +15,6 @@
- [Working with Monitors](#monitors)
- [MariaDB MaxScale Status Commands](#statuscommands)
- [Administration Commands](#admincommands)
- [Configuring MariaDB MaxScale to Accept MaxAdmin Connections](#connections)
- [Tuning MariaDB MaxScale](#tuning)
<a name="overview"></a>
@ -30,53 +30,145 @@ MaxAdmin supports
* Execution of command scripts
<a name="configuring"></a>
# Configuring MariaDB MaxScale for MaxAdmin
In order to be able to use MaxAdmin, MariaDB MaxScale must be configured for it.
There are two ways MaxAdmin can connect to to MaxScale.
* Using a Unix domain socket.
* Using a hostname and port.
The first alternative is introduced in MaxScale 2.0 and is the secure and
recommended way. The second alternative is available for backward compatibility,
but is _insecure_ and **deprecated** and _will be removed in a future version of
MaxScale_.
An example configuration looks as follows:
```
[MaxAdmin]
type=service
router=cli
[MaxAdmin Unix Listener]
type=listener
service=MaxAdmin
protocol=maxscaled
socket=default
[MaxAdmin Inet Listener]
type=listener
service=MaxAdmin
protocol=maxscaled
address=localhost
port=6603
```
In the configuration above, two listeners are created; one listening on the default
Unix domain socket and one listening on the default port.
Which approach is used has other implications than just how the communication between
MaxAdmin and MariaDB MaxScale is handled. In the former case, the authorization is
based upon the Linux identity and in the latter case on explicitly created user
accounts that have **no** relationship to the Linux accounts.
Note that if the socket path or port are changed, then MaxAdmin has to be invoked
with `-S` or `-P` respectively.
<a name="running"></a>
# Running MaxAdmin
Depending on whether MariaDB MaxScale has been configured to use Unix domain sockets
or internet sockets, MaxAdmin needs to be invoked slightly differently.
If Unix domain sockets are used, then MaxAdmin needs no additional arguments:
alice@host$ maxadmin
MaxAdmin>
The above implies that the Linux user _alice_ has been enabled to use MaxAdmin.
If internet sockets are used, then either the host, port, user or password has
to be specified explicitly:
alice@host$ maxadmin -u maxscale-admin
Password:
MaxScale>
If Unix domain sockets are used, then initially only `root` has access. MaxAdmin
usage can subsequently be enabled for other Linux users.
The MaxAdmin client application may be run in two different modes, either as an interactive command shell for executing commands against MariaDB MaxScale or by passing commands on the MaxAdmin command line itself.
<a name="interface"></a>
# Working With Administration Interface Users
MaxScale communicates with MariaDB MaxScale using UNIX domain sockets, which means that it can only be used on the very host where MariaDB MaxScale is running. Initially MaxAdmin can connect only when run as `root`. Other Linux users can subsequently be allowed access.
**NOTE**: Remote access with -h and -P options is no longer supported.
## What Users Have Been Defined?
In order to see the current users (UNIX users) that have been defined for the administration interface use the command _show users_.
In order to see the Linux users for whom MaxAdmin usage has been enabled and
any explicitly created accounts, use the command _show users_.
MaxScale> show users
Administration interface users:
User names: vilho, dba, massi, mark
Enabled Linux accounts (secure) : alice, bob, cecil
Created network accounts (insecure): maxscale-admin
MaxScale>
Please note `root` will not be shown.
Please note that `root` will not be shown.
MaxScale> show users
Administration interface users:
No administration users have been defined.
MaxScale>
## Enabling a Linux account
To enable MaxAdmin usage for a particular Linux account, use the command _enable account_.
This command is passed a user name, which should be the same as that of an existing Linux user.
MaxScale> enable account bob
Note that it is not checked that the provided name indeed corresponds to an existing
Linux account, so it is possible to enable an account that does not exist yet.
Note also that it is possible to enable a Linux account irrespective of how MaxAdmin
has connected to MariaDB MaxScale. That is, the command is not restricted to MaxAdmin
users connecting over a Unix domain socket.
## Disabling a Linux account
To disable MaxAdmin usage for a particular Linux account, use the command _disable account_.
This command is passed a user name, which should be a Linux user for whom MaxAdmin usage
earlier has been enabled.
MaxScale> disable account bob
Note also that it is possible to disable a Linux account irrespective of how MaxAdmin
has connected to MariaDB MaxScale. That is, the command is not restricted to MaxAdmin
users connecting over a Unix domain socket.
Note that it is possible to disable the current user, but that will only affect the
next attempt to use MaxAdmin. `root` cannot be removed.
## Add A New User
To add a new administrative user to the MariaDB MaxScale server use the command _add user_. This command is passed a user name, which should be the same as that of an existing Linux user.
To add a new MaxAdmin user to be used when MaxAdmin connects over an internet socket,
use the command _add user_. This command is passed a user name and a password.
MaxScale> add user maria
User maria has been successfully added.
MaxScale> add user maxscale-admin secretpwd
User maxscale-admin has been successfully added.
MaxScale>
Note that a user that is given the rights to use MaxAdmin, has the very same rights `root` has, including adding and removing users.
Note that there is no difference in rights between an enabled Linux account and an
explicitly created user.
## Delete A User
To remove a user the command _remove user_ is used and it is simply invoked with the user to be removed.
To remove a user the command _remove user_ is used and it is invoked with the
username and password.
MaxScale> remove user maria
User maria has been successfully removed.
MaxScale> remove user maxscale-admin secretpwd
User maxscale-admin has been successfully removed.
MaxScale>
Note that it is possible to remove the current user, but that will only affect the next attempt to use MaxAdmin. `root` cannot be removed.
Note that it is possible to remove the current user, but that will only affect the
next attempt to use MaxAdmin.
# Command Line Switches
@ -93,6 +185,26 @@ The MaxAdmin command accepts a number of switches
<td>--socket=...</td>
<td>The UNIX domain socket path that MaxAdmin will use to connect to the MariaDB MaxScale server. If no -S option is given then the default socket path /tmp/maxadmin.sock will be used.</td>
</tr>
<tr>
<td>-u user</td>
<td>--user=...</td>
<td>Sets the username that will be used for the MaxScale connection. If no -u option is passed on the MaxAdmin command line then the default username of ‘admin’ will be used.</td>
</tr>
<tr>
<td>-p password</td>
<td>--password=...</td>
<td>Sets the user password that will be used. If no -p option is passed on the command line then MaxAdmin will prompt for interactive entry of the password.</td>
</tr>
<tr>
<td>-h hostname</td>
<td>--hostname=...</td>
<td>The hostname of the MaxScale server to connect to. If no -h option is passed on the command line then MaxAdmin will attempt to connect to the host ‘localhost’.</td>
</tr>
<tr>
<td>-P port</td>
<td>--port=...</td>
<td>The port that MaxAdmin will use to connect to the MaxScale server. if no -P option is given then the default port of 6603 will be used.</td>
</tr>
<tr>
<td>-?</td>
<td>--help</td>
@ -835,28 +947,6 @@ A command, _reload config_, is available that will cause MariaDB MaxScale to rel
The MariaDB MaxScale server may be shutdown using the _shutdown maxscale_ command.
<a name="connections"></a>
# Configuring MariaDB MaxScale to Accept MaxAdmin Connections
In order to enable the use of MaxAdmin, the service CLI with an accompanying listener must be added to the MariaDB MaxScale configuration file.
The default entries required are shown below.
[CLI]
type=service
router=cli
[CLI Listener]
type=listener
service=CLI
protocol=maxscaled
socket=default
#socket=/somepath/maxadmin.socket
**NOTE**: As the protocol maxscaled only supports UNIX domain sockets it is thus not possible to connect remotely to MariaDB MaxScale.
In the example, the default socket path (/tmp/maxadmin.sock) is used. It can be changed to an specific path and in that case MaxAdmin must be invoked with the -S option.
<a name="tuning"></a>
# Tuning MariaDB MaxScale

50
Documentation/Release-Notes/MaxScale-2.0.1-Release-Notes.md
View File

@ -5,16 +5,12 @@ Release 2.0.1 is a GA release.
This document describes the changes in release 2.0.1, when compared to
[release 2.0.0](MaxScale-2.0.0-Release-Notes.md).
If you are upgrading from 1.4.3, please also read the release notes
of [2.0.0](./MaxScale-2.0.0-Release-Notes.md).
For any problems you encounter, please consider submitting a bug
report at [Jira](https://jira.mariadb.org).
## License
The license of MaxScale has been changed from GPLv2 to MariaDB BSL.
For more information about MariaDB BSL, please refer to
[MariaDB BSL](https://www.mariadb.com/bsl).
## Updated Features
### Routing hint priority change
@ -34,6 +30,42 @@ would be routed to the slave.
[ReadWriteSplit](../Routers/ReadWriteSplit.md) documentation before using
routing hints.
### MaxAdmin Usage
In 2.0.0 (Beta), the authentication mechanism of MaxAdmin was completely
changed, so that MaxAdmin could only connect to MaxScale using a Unix domain
socket, thus _only when run on the same host_, and authorization was based
on the Unix identity. Remote access was no longer supported.
To the user this was visible so that while you in 1.4.3 had to provide
a password when starting _maxadmin_ and when adding a user
```
user@host $ maxadmin -p password
MaxAdmin> add user john johns-password
```
in 2.0.0 (Beta), where only Unix domain sockets could be used, you did not
have to provide a password neither when starting _maxadmin_, nor when adding
users
```
user@host $ maxadmin
MaxAdmin> add user john
```
as the MaxScale user corresponded to a Unix user, provided the Linux user
had been added as a user of MaxScale.
In 2.0.1 (GA) this has been changed so that the 1.4.3 behaviour is intact
but _deprecated_, and the 2.0.0 (Beta) behaviour is exposed using a new set
of commands:
```
MaxAdmin> enable account alice
MaxAdmin> disable account alice
```
Note that the way you need to invoke _maxadmin_ depends upon how MariaDB
MaxScale has been configued.
Please consult
[MaxAdmin documentation](../Reference/MaxAdmin.md) for more details.
## Bug fixes
[Here is a list of bugs fixed since the release of MaxScale 2.0.1.](https://jira.mariadb.org/issues/?jql=project%20%3D%20MXS%20AND%20issuetype%20%3D%20Bug%20AND%20status%20%3D%20Closed%20AND%20fixVersion%20in%20(2.0.0%2C%202.0.1)%20AND%20resolved%20%3E%3D%20-21d%20ORDER%20BY%20priority%20DESC%2C%20updated%20DESC)
@ -43,12 +75,10 @@ would be routed to the slave.
* [MXS-842](https://jira.mariadb.org/browse/MXS-842): Unexpected / undocumented behaviour when multiple available masters from mmmon monitor
* [MXS-846](https://jira.mariadb.org/browse/MXS-846): MMMon: Maintenance mode on slave logs error message every second
## Known Issues and Limitations
There are some limitations and known issues within this version of MaxScale.
For more information, please refer to the [Limitations](../About/Limitations.md)
document.
For more information, please refer to the [Limitations](../About/Limitations.md) document.
## Packaging

34
Documentation/Routers/CLI.md
View File

@ -1,10 +1,13 @@
# CLI
The command line interface as used by `maxadmin`. This is a variant of the debugcli that is built slightly differently so that it may be accessed by the client application `maxadmin`. The CLI requires the use of the `maxscaled` protocol.
The command line interface as used by `maxadmin`. The _CLI_ router requires the use
of the `maxscaled` protocol.
## Configuration
There are two components to the definition required in order to run the command line interface to use with MaxAdmin; a service and a listener.
Two components are required in order to run the command line interface for use with
_maxadmin_; a service and a listener. The listener may either use a Unix domain socket
or an internet socket.
The default entries required are shown below.
@ -13,9 +16,34 @@ The default entries required are shown below.
type=service
router=cli
[CLI Listener]
# Unix Domain Socket
[CLI Unix Listener]
type=listener
service=CLI
protocol=maxscaled
socket=default
# Internet Socket
[CLI Inet Listener]
type=listener
service=CLI
protocol=maxscaled
address=localhost
port=6603
```
In the example above, two listeners have been specified; one that listens on the
default Unix domain socket and one that listens on the default port. In the latter
case, if the `address=` entry is removed, connections are allowed from any machine
on your network.
In the former case, if the value of `socket` is changed and in the latter case,
if the value of `port` is changed, _maxadmin_ must be invoked with the `-S` and
`-P` options respectively.
Note that if Unix domain sockets are used, the connection is secure, but _maxadmin_
can only be used on the same host where MariaDB MaxScale runs. If internet sockets
are used, the connection is _inherently insecure_ but _maxadmin_ can be used from
another host than the one where MariaDB MaxScale runs.
Note that the latter approach is **deprecated** and will be removed in a future
version of MariaDB MaxScale.

3
Documentation/Tutorials/Galera-Cluster-Connection-Routing-Tutorial.md
View File

@ -117,9 +117,6 @@ The final stage in the configuration is to add the option service which is used
protocol=maxscaled
socket=default
**Note**: maxscaled protocol supports only UNIX domain sockets and in the example default is set.
Changing it requires maxadmin to use -S with the new path. Default /tmp/maxadmin.sock is for both maxadmin and maxscaled.
## Starting MariaDB MaxScale
Upon completion of the configuration process MariaDB MaxScale is ready to be started for the first time. This may either be done manually by running the maxscale command or via the service interface.

3
Documentation/Tutorials/Galera-Cluster-Read-Write-Splitting-Tutorial.md
View File

@ -147,9 +147,6 @@ protocol=maxscaled
socket=default
```
**Note**: maxscaled protocol supports only UNIX domain sockets and in the example default is set.
Changing it requires maxadmin to use -S with the new path. Default /tmp/maxadmin.sock is for both maxadmin and maxscaled.
## Starting MariaDB MaxScale
Upon completion of the configuration process MariaDB MaxScale is ready to be started for the first time. This may either be done manually by running the maxscale command or via the service interface.

2
Documentation/Tutorials/MySQL-Replication-Connection-Routing-Tutorial.md
View File

@ -174,8 +174,6 @@ service=CLI
protocol=maxscaled
socket=default
```
**Note**: maxscaled protocol supports only UNIX domain sockets and in the example default is set.
Changing it requires maxadmin to use -S with the new path. Default /tmp/maxadmin.sock is for both maxadmin and maxscaled.
# Starting MariaDB MaxScale

2
Documentation/Tutorials/MySQL-Replication-Read-Write-Splitting-Tutorial.md
View File

@ -133,8 +133,6 @@ service=CLI
protocol=maxscaled
socket=default
```
**Note**: maxscaled protocol supports only UNIX domain sockets and in the example default is set.
Changing it requires maxadmin to use -S with the new path. Default /tmp/maxadmin.sock is for both maxadmin and maxscaled.
# Starting MariaDB MaxScale

3
Documentation/Tutorials/Nagios-Plugins.md
View File

@ -62,8 +62,7 @@ service=AdminInterface
protocol=maxscaled
socket=default
```
**Note**: maxscaled protocol supports only UNIX domain sockets and in the example default is set.
Changing it requires maxadmin to use -S with the new path. Default /tmp/maxadmin.sock is for both maxadmin and maxscaled.
## Prepare Nagios configuration files.
Assuming Nagios installed on a separated server and the plugins are in /usr/lib64/nagios/plugins and configuration files are in /etc/nagios:

2
Documentation/Tutorials/RabbitMQ-And-Tee-Archiving.md
View File

@ -208,7 +208,7 @@ router=cli
type=listener
service=MaxAdmin Service
protocol=maxscaled
port=6603
socket=default
```
Now we have created the MariaDB MaxScale configuration file and all we need to do is to save

37
Documentation/Upgrading/Upgrading-To-MaxScale-2.0.md
View File

@ -12,37 +12,18 @@ configuration file.
## MaxAdmin
The way a user of MaxAdmin is authenticated has been completely changed.
In 2.0, MaxAdmin can only connect to MariaDB MaxScale using a domain socket, thus
_only when run on the same host_, and authorization is based upon the UNIX
identity. Remote access is no longer supported.
The default way the communication between MaxAdmin and MariaDB MaxScale is
handled has been changed from an internet socket to a Unix domain socket.
The former alternative is still available but has been _deprecated_.
When 2.0 has been installed, MaxAdmin can only be used by `root` and
other users must be added anew. Please consult
[MaxAdmin documentation](../Reference/MaxAdmin.md) for more details.
If no arguments are given to MaxAdmin, it will attempt to connect to
MariaDB MaxScale using a Unix domain socket. After the upgrade you will
need to provide at least one internet socket related flag - `-h`, `-P`,
`-u` or `-p` - to force MaxAdmin to use the internet socket approach.
This change requires the _maxscaled_ protocol listener entry in the
MaxScale configuration file to be updated; address and port information
must be replaced with socket information. For instance, an entry like
```
[MaxAdmin Listener]
type=listener
protocol=maxscaled
address=localhost
port=6603
```
should be updated to
```
[MaxAdmin Listener]
type=listener
protocol=maxscaled
socket=default
```
where `default` corresponds to `/tmp/maxadmin.sock`.
E.g.
Note that if this update is *not* made, maxscaled will log a warning
and use the default socket path. This behaviour may change in later
releases of MaxScale.
user@host $ maxadmin -u admin
## MySQL Monitor