diff --git a/Documentation/Authenticators/PAM-Authenticator.md b/Documentation/Authenticators/PAM-Authenticator.md index 4e918413b..cd85ce23d 100644 --- a/Documentation/Authenticators/PAM-Authenticator.md +++ b/Documentation/Authenticators/PAM-Authenticator.md @@ -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 diff --git a/Documentation/Monitors/MariaDB-Monitor.md b/Documentation/Monitors/MariaDB-Monitor.md index 07543619b..f18273395 100644 --- a/Documentation/Monitors/MariaDB-Monitor.md +++ b/Documentation/Monitors/MariaDB-Monitor.md @@ -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.