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

Update documentation for 2.4.1

Browse Source 
Small changes to MariaDBMonitor and Pam authenticator.
This commit is contained in:
Esa Korhonen
2019-08-14 18:15:54 +03:00
parent 33ae9d3a2f
commit 29ec15c8eb
2 changed files with 70 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
Documentation/Authenticators/PAM-Authenticator.md
View File

@ -29,15 +29,14 @@ protocol=MariaDBBackend
authenticator=PAMBackendAuth authenticator=PAMBackendAuth
``` ```
The PAM authenticator fetches user entries with `plugin='pam'` from The PAM authenticator fetches user entries with `plugin='pam'` from the
the `mysql.user` table of a backend. The user accounts also need to have either `mysql.user` table of a backend. The user accounts also need to have either the
the global SELECT-privilege or a database or a table-level privilege. The PAM global SELECT-privilege or a database or a table-level privilege. Privileges
service name of a user is read from the `authetication_string`-column. The through a default role are also detected. The PAM service name of a user is read
matching PAM service in the operating system PAM config is used for from the `authetication_string`-column. The matching PAM service in the
authenticating the user. If the `authetication_string` for a user is empty, operating system PAM config is used for authenticating the user. If the
the fallback service `mysql` is used. If a username@host-combination matches `authetication_string` for a user is empty, the fallback service `mysql` is
multiple rows, they will all be attempted until authentication succeeds or all used.
services fail.
PAM service configuration is out of the scope of this document, see PAM service configuration is out of the scope of this document, see
[The Linux-PAM System Administrators' Guide [The Linux-PAM System Administrators' Guide
@ -51,29 +50,31 @@ account required pam_unix.so
## Anonymous user mapping ## Anonymous user mapping
The MaxScale PAM authenticator supports a limited version of [user The MaxScale PAM authenticator supports a limited version of
mapping](https://mariadb.com/kb/en/library/user-and-group-mapping-with-pam/). It requires [user mapping](https://mariadb.com/kb/en/library/user-and-group-mapping-with-pam/).
less configuration but is also less accurate than the server authentication. Anonymous It requires less configuration but is also less accurate than the server
mapping is enabled in MaxScale if the following user exists: authentication. Anonymous mapping is enabled in MaxScale if the following user
exists:
- Empty username (e.g. `''@'%'` or `''@'myhost.com'`) - Empty username (e.g. `''@'%'` or `''@'myhost.com'`)
- `plugin = 'pam'` - `plugin = 'pam'`
- Proxy grant is on (The query `SHOW GRANTS FOR user@host;` returns at least one row with - Proxy grant is on (The query `SHOW GRANTS FOR user@host;` returns at least one
`GRANT PROXY ON ...`) row with `GRANT PROXY ON ...`)
When the authenticator detects such users, anonymous account mapping is enabled for the When the authenticator detects such users, anonymous account mapping is enabled
hosts of the anonymous users. To verify this, enable the info log (`log_info=1` in for the hosts of the anonymous users. To verify this, enable the info log
MaxScale config file) and look for messages such as "Found 2 anonymous PAM user(s) ..." (`log_info=1` in MaxScale config file) and look for messages such as "Found 2
and "Added anonymous PAM user ..." during MaxScale startup. anonymous PAM user(s) ..." and "Added anonymous PAM user ..." during MaxScale
startup.
When mapping is on, the MaxScale PAM authenticator does not require client accounts to When mapping is on, the MaxScale PAM authenticator does not require client
exist in the `mysql.user`-table received from the backend. MaxScale only requires that the accounts to exist in the `mysql.user`-table received from the backend. MaxScale
hostname of the incoming client matches the host field of one of the anonymous users only requires that the hostname of the incoming client matches the host field of
(comparison performed using `LIKE`). If a match is found, MaxScale attempts to one of the anonymous users (comparison performed using `LIKE`). If a match is
authenticate the client to the local machine with the username and password supplied. The found, MaxScale attempts to authenticate the client to the local machine with
PAM service used for authentication is read from the `authentication_string`-field of the the username and password supplied. The PAM service used for authentication is
anonymous user. If authentication was successful, MaxScale then uses the username and read from the `authentication_string`-field of the anonymous user. If
password to log to the backends. If the client host matches multiple anonymous hosts, authentication was successful, MaxScale then uses the username and password to
authentication is attempted with all of their PAM services until one succeeds or all fail. log to the backends.
Anonymous mapping is only attempted if the client username is not found in the Anonymous mapping is only attempted if the client username is not found in the
`mysql.user`-table as explained in [Configuration](#configuration). This means, `mysql.user`-table as explained in [Configuration](#configuration). This means,
@ -81,14 +82,16 @@ that if a user is found and the authentication fails, anonymous authentication
is not attempted even when it could use a different PAM service with a different is not attempted even when it could use a different PAM service with a different
outcome. outcome.
Setting up PAM group mapping for the MariaDB server is a more involved process as the Setting up PAM group mapping for the MariaDB server is a more involved process
server requires details on which Unix user or group is mapped to which MariaDB user. See as the server requires details on which Unix user or group is mapped to which
MariaDB user. See
[this guide](https://mariadb.com/kb/en/library/configuring-pam-authentication-and-user-mapping-with-unix-authentication/) [this guide](https://mariadb.com/kb/en/library/configuring-pam-authentication-and-user-mapping-with-unix-authentication/)
for more details. Performing all the steps in the guide also on the MaxScale machine is for more details. Performing all the steps in the guide also on the MaxScale
not required, as the MaxScale PAM plugin only checks that the client host matches an machine is not required, as the MaxScale PAM plugin only checks that the client
anonymous user and that the client (with the username and password it provided) can log host matches an anonymous user and that the client (with the username and
into the local PAM configuration. If using normal password authentication, simply password it provided) can log into the local PAM configuration. If using normal
generating the Unix user and password should be enough. password authentication, simply generating the Unix user and password should be
enough.
## Implementation details and limitations ## Implementation details and limitations
@ -101,16 +104,16 @@ MaxScale to successfully log into the servers, the messages and answers need to
be predefined. This requirement denies the use of more exotic schemes such as be predefined. This requirement denies the use of more exotic schemes such as
one-time passwords or two-factor authentication. one-time passwords or two-factor authentication.
The MaxScale PAM authentication module only supports a The MaxScale PAM authentication module only supports a simple password exchange.
simple password exchange. On the client side, the authentication begins with On the client side, the authentication begins with MaxScale sending an
MaxScale sending an AuthSwitchRequest packet. In addition to the command, the AuthSwitchRequest packet. In addition to the command, the packet contains the
packet contains the client plugin name `dialog`, a message type byte `4` and the client plugin name `dialog`, a message type byte `4` and the message
message `Password: `. In the next packet, the client should send the password, `Password: `. In the next packet, the client should send the password, which
which MaxScale will forward to the PAM API running on the local machine. If the MaxScale will forward to the PAM API running on the local machine. If the
password is correct, an OK packet is sent to the client. If the local PAM API asks password is correct, an OK packet is sent to the client. If the local PAM API
for additional credentials as is typical in two-factor authentication schemes, asks for additional credentials as is typical in two-factor authentication
authentication fails. Informational messages such as password expiration schemes, authentication fails. Informational messages such as password
notifications are allowed. These are simply printed to the log. expiration notifications are allowed. These are simply printed to the log.
On the backend side, MaxScale expects the servers to act as MaxScale did towards On the backend side, MaxScale expects the servers to act as MaxScale did towards
the client. The servers should send an AuthSwitchRequest packet as defined the client. The servers should send an AuthSwitchRequest packet as defined

39
Documentation/Monitors/MariaDB-Monitor.md
View File

@ -144,13 +144,16 @@ switchover and rejoin-specific parameters are listed in their own
### `assume_unique_hostnames` ### `assume_unique_hostnames`
Boolean, default: ON. When active, the monitor assumes that server hostnames and Boolean, default: ON. When active, the monitor assumes that server hostnames and
ports are consistent between the MaxScale configuration file server definitions ports are consistent between the server definitions in the MaxScale
and the "SHOW ALL SLAVES STATUS" outputs of the servers. Specifically, the configuration file and the "SHOW ALL SLAVES STATUS" outputs of the servers
monitor assumes that if server A is replicating from server B, then A must have themselves. Specifically, the monitor assumes that if server A is replicating
a slave connection with `Master_Host` and `Master_Port` equal to B's address and from server B, then A must have a slave connection with `Master_Host` and
port in the configuration file. If this is not the case, e.g. an IP is used in `Master_Port` equal to B's address and port in the configuration file. If this
the server while a hostname is given in the file, the monitor will misinterpret is not the case, e.g. an IP is used in the server while a hostname is given in
the topology. the file, the monitor may misinterpret the topology. In MaxScale 2.4.1, the
monitor attempts name resolution on the addresses if a simple string comparison
does not find a match. Using exact matching addresses is, however, more
reliable.
This setting must be ON to use any cluster operation features such as failover This setting must be ON to use any cluster operation features such as failover
or switchover, because MaxScale uses the addresses and ports in the or switchover, because MaxScale uses the addresses and ports in the
@ -340,11 +343,11 @@ selection criteria is as follows in descending priority:
2. If the new master has unprocessed relay log items, cancel and try again 2. If the new master has unprocessed relay log items, cancel and try again
later. later.
3. Prepare the new master: 3. Prepare the new master:
1. Remove the slave connection the new master used to replicate from the old 1. Remove the slave connection the new master used to replicate from the
master. old master.
2. Disable the *read\_only*-flag. 2. Disable the *read\_only*-flag.
3. Enable scheduled server events (if event handling is on). Only events that were 3. Enable scheduled server events (if event handling is on). Only events
enabled on the old master are enabled. that were enabled on the old master are enabled.
4. Run the commands in `promotion_sql_file`. 4. Run the commands in `promotion_sql_file`.
5. Start replication from external master if one existed. 5. Start replication from external master if one existed.
4. Redirect all other slaves to replicate from the new master: 4. Redirect all other slaves to replicate from the new master:
@ -353,15 +356,16 @@ later.
3. START SLAVE 3. START SLAVE
5. Check that all slaves are replicating. 5. Check that all slaves are replicating.
Failover is considered successful if steps 1 to 3 succeeded, as the cluster then has at Failover is considered successful if steps 1 to 3 succeed, as the cluster then
least a valid master server. has at least a valid master server.
**Switchover** swaps a running master with a running slave. It does the **Switchover** swaps a running master with a running slave. It does the
following: following:
1. Prepare the old master for demotion: 1. Prepare the old master for demotion:
1. Stop any external replication. 1. Stop any external replication.
2. Kill connections from super-users since *read\_only* does not affect them. 2. Kill connections from super-users since *read\_only* does not affect
them.
3. Enable the *read\_only*-flag to stop writes. 3. Enable the *read\_only*-flag to stop writes.
4. Disable scheduled server events (if event handling is on). 4. Disable scheduled server events (if event handling is on).
5. Run the commands in `demotion_sql_file`. 5. Run the commands in `demotion_sql_file`.
@ -400,9 +404,10 @@ operation proceeds as follows:
*gtid\_current\_pos*. *gtid\_current\_pos*.
2. Prepare new master: 2. Prepare new master:
1. Disable the *read\_only*-flag. 1. Disable the *read\_only*-flag.
2. Enable scheduled server events (if event handling is on). Events are only enabled 2. Enable scheduled server events (if event handling is on). Events are
if the cluster had a master server when starting the reset-replication operation. only enabled if the cluster had a master server when starting the
Only events that were enabled on the previous master are enabled on the new. reset-replication operation. Only events that were enabled on the previous
master are enabled on the new.
3. Direct other servers to replicate from the new master as in the other 3. Direct other servers to replicate from the new master as in the other
operations. operations.