Update documentation for 2.4.1
Small changes to MariaDBMonitor and Pam authenticator.
This commit is contained in:
Esa Korhonen
parent
33ae9d3a2f
commit
29ec15c8eb
@ -29,15 +29,14 @@ protocol=MariaDBBackend
|
||||
authenticator=PAMBackendAuth
|
||||
```
|
||||
|
||||
The PAM authenticator fetches user entries with `plugin='pam'` from
|
||||
the `mysql.user` table of a backend. The user accounts also need to have either
|
||||
the global SELECT-privilege or a database or a table-level privilege. The PAM
|
||||
service name of a user is read from the `authetication_string`-column. The
|
||||
matching PAM service in the operating system PAM config is used for
|
||||
authenticating the user. If the `authetication_string` for a user is empty,
|
||||
the fallback service `mysql` is used. If a username@host-combination matches
|
||||
multiple rows, they will all be attempted until authentication succeeds or all
|
||||
services fail.
|
||||
The PAM authenticator fetches user entries with `plugin='pam'` from the
|
||||
`mysql.user` table of a backend. The user accounts also need to have either the
|
||||
global SELECT-privilege or a database or a table-level privilege. Privileges
|
||||
through a default role are also detected. The PAM service name of a user is read
|
||||
from the `authetication_string`-column. The matching PAM service in the
|
||||
operating system PAM config is used for authenticating the user. If the
|
||||
`authetication_string` for a user is empty, the fallback service `mysql` is
|
||||
used.
|
||||
|
||||
PAM service configuration is out of the scope of this document, see
|
||||
[The Linux-PAM System Administrators' Guide
|
||||
@ -51,29 +50,31 @@ account required pam_unix.so
|
||||
|
||||
## Anonymous user mapping
|
||||
|
||||
The MaxScale PAM authenticator supports a limited version of [user
|
||||
mapping](https://mariadb.com/kb/en/library/user-and-group-mapping-with-pam/). It requires
|
||||
less configuration but is also less accurate than the server authentication. Anonymous
|
||||
mapping is enabled in MaxScale if the following user exists:
|
||||
The MaxScale PAM authenticator supports a limited version of
|
||||
[user mapping](https://mariadb.com/kb/en/library/user-and-group-mapping-with-pam/).
|
||||
It requires less configuration but is also less accurate than the server
|
||||
authentication. Anonymous mapping is enabled in MaxScale if the following user
|
||||
exists:
|
||||
- Empty username (e.g. `''@'%'` or `''@'myhost.com'`)
|
||||
- `plugin = 'pam'`
|
||||
- Proxy grant is on (The query `SHOW GRANTS FOR user@host;` returns at least one row with
|
||||
`GRANT PROXY ON ...`)
|
||||
- Proxy grant is on (The query `SHOW GRANTS FOR user@host;` returns at least one
|
||||
row with `GRANT PROXY ON ...`)
|
||||
|
||||
When the authenticator detects such users, anonymous account mapping is enabled for the
|
||||
hosts of the anonymous users. To verify this, enable the info log (`log_info=1` in
|
||||
MaxScale config file) and look for messages such as "Found 2 anonymous PAM user(s) ..."
|
||||
and "Added anonymous PAM user ..." during MaxScale startup.
|
||||
When the authenticator detects such users, anonymous account mapping is enabled
|
||||
for the hosts of the anonymous users. To verify this, enable the info log
|
||||
(`log_info=1` in MaxScale config file) and look for messages such as "Found 2
|
||||
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
|
||||
exist in the `mysql.user`-table received from the backend. MaxScale only requires that the
|
||||
hostname of the incoming client matches the host field of one of the anonymous users
|
||||
(comparison performed using `LIKE`). If a match is found, MaxScale attempts to
|
||||
authenticate the client to the local machine with the username and password supplied. The
|
||||
PAM service used for authentication is read from the `authentication_string`-field of the
|
||||
anonymous user. If authentication was successful, MaxScale then uses the username and
|
||||
password to log to the backends. If the client host matches multiple anonymous hosts,
|
||||
authentication is attempted with all of their PAM services until one succeeds or all fail.
|
||||
When mapping is on, the MaxScale PAM authenticator does not require client
|
||||
accounts to exist in the `mysql.user`-table received from the backend. MaxScale
|
||||
only requires that the hostname of the incoming client matches the host field of
|
||||
one of the anonymous users (comparison performed using `LIKE`). If a match is
|
||||
found, MaxScale attempts to authenticate the client to the local machine with
|
||||
the username and password supplied. The PAM service used for authentication is
|
||||
read from the `authentication_string`-field of the anonymous user. If
|
||||
authentication was successful, MaxScale then uses the username and password to
|
||||
log to the backends.
|
||||
|
||||
Anonymous mapping is only attempted if the client username is not found in the
|
||||
`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
|
||||
outcome.
|
||||
|
||||
Setting up PAM group mapping for the MariaDB server is a more involved process as the
|
||||
server requires details on which Unix user or group is mapped to which MariaDB user. See
|
||||
Setting up PAM group mapping for the MariaDB server is a more involved process
|
||||
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/)
|
||||
for more details. Performing all the steps in the guide also on the MaxScale machine is
|
||||
not required, as the MaxScale PAM plugin only checks that the client host matches an
|
||||
anonymous user and that the client (with the username and password it provided) can log
|
||||
into the local PAM configuration. If using normal password authentication, simply
|
||||
generating the Unix user and password should be enough.
|
||||
for more details. Performing all the steps in the guide also on the MaxScale
|
||||
machine is not required, as the MaxScale PAM plugin only checks that the client
|
||||
host matches an anonymous user and that the client (with the username and
|
||||
password it provided) can log into the local PAM configuration. If using normal
|
||||
password authentication, simply generating the Unix user and password should be
|
||||
enough.
|
||||
|
||||
## 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
|
||||
one-time passwords or two-factor authentication.
|
||||
|
||||
The MaxScale PAM authentication module only supports a
|
||||
simple password exchange. On the client side, the authentication begins with
|
||||
MaxScale sending an AuthSwitchRequest packet. In addition to the command, the
|
||||
packet contains the client plugin name `dialog`, a message type byte `4` and the
|
||||
message `Password: `. In the next packet, the client should send the password,
|
||||
which 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
|
||||
for additional credentials as is typical in two-factor authentication schemes,
|
||||
authentication fails. Informational messages such as password expiration
|
||||
notifications are allowed. These are simply printed to the log.
|
||||
The MaxScale PAM authentication module only supports a simple password exchange.
|
||||
On the client side, the authentication begins with MaxScale sending an
|
||||
AuthSwitchRequest packet. In addition to the command, the packet contains the
|
||||
client plugin name `dialog`, a message type byte `4` and the message
|
||||
`Password: `. In the next packet, the client should send the password, which
|
||||
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 for additional credentials as is typical in two-factor authentication
|
||||
schemes, authentication fails. Informational messages such as password
|
||||
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
|
||||
the client. The servers should send an AuthSwitchRequest packet as defined
|
||||
|
||||
@ -144,13 +144,16 @@ switchover and rejoin-specific parameters are listed in their own
|
||||
### `assume_unique_hostnames`
|
||||
|
||||
Boolean, default: ON. When active, the monitor assumes that server hostnames and
|
||||
ports are consistent between the MaxScale configuration file server definitions
|
||||
and the "SHOW ALL SLAVES STATUS" outputs of the servers. Specifically, the
|
||||
monitor assumes that if server A is replicating from server B, then A must have
|
||||
a slave connection with `Master_Host` and `Master_Port` equal to B's address and
|
||||
port in the configuration file. If this is not the case, e.g. an IP is used in
|
||||
the server while a hostname is given in the file, the monitor will misinterpret
|
||||
the topology.
|
||||
ports are consistent between the server definitions in the MaxScale
|
||||
configuration file and the "SHOW ALL SLAVES STATUS" outputs of the servers
|
||||
themselves. Specifically, the monitor assumes that if server A is replicating
|
||||
from server B, then A must have a slave connection with `Master_Host` and
|
||||
`Master_Port` equal to B's address and port in the configuration file. If this
|
||||
is not the case, e.g. an IP is used in the server while a hostname is given in
|
||||
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
|
||||
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
|
||||
later.
|
||||
3. Prepare the new master:
|
||||
1. Remove the slave connection the new master used to replicate from the old
|
||||
master.
|
||||
1. Remove the slave connection the new master used to replicate from the
|
||||
old master.
|
||||
2. Disable the *read\_only*-flag.
|
||||
3. Enable scheduled server events (if event handling is on). Only events that were
|
||||
enabled on the old master are enabled.
|
||||
3. Enable scheduled server events (if event handling is on). Only events
|
||||
that were enabled on the old master are enabled.
|
||||
4. Run the commands in `promotion_sql_file`.
|
||||
5. Start replication from external master if one existed.
|
||||
4. Redirect all other slaves to replicate from the new master:
|
||||
@ -353,15 +356,16 @@ later.
|
||||
3. START SLAVE
|
||||
5. Check that all slaves are replicating.
|
||||
|
||||
Failover is considered successful if steps 1 to 3 succeeded, as the cluster then has at
|
||||
least a valid master server.
|
||||
Failover is considered successful if steps 1 to 3 succeed, as the cluster then
|
||||
has at least a valid master server.
|
||||
|
||||
**Switchover** swaps a running master with a running slave. It does the
|
||||
following:
|
||||
|
||||
1. Prepare the old master for demotion:
|
||||
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.
|
||||
4. Disable scheduled server events (if event handling is on).
|
||||
5. Run the commands in `demotion_sql_file`.
|
||||
@ -400,9 +404,10 @@ operation proceeds as follows:
|
||||
*gtid\_current\_pos*.
|
||||
2. Prepare new master:
|
||||
1. Disable the *read\_only*-flag.
|
||||
2. Enable scheduled server events (if event handling is on). Events are only enabled
|
||||
if the cluster had a master server when starting the reset-replication operation.
|
||||
Only events that were enabled on the previous master are enabled on the new.
|
||||
2. Enable scheduled server events (if event handling is on). Events are
|
||||
only enabled if the cluster had a master server when starting the
|
||||
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
|
||||
operations.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user