Merge branch '2.2' into 2.3

Documentation/Authenticators/PAM-Authenticator.md

@@ -29,13 +29,15 @@ protocol=MariaDBBackend
 authenticator=PAMBackendAuth
 ```
 
-The client PAM authenticator will fetch user entries with `plugin='pam'` from
-the `mysql.user` table. The entries should also have a PAM service name set in
-the `authetication_string` column. The matching PAM service in the operating
-system PAM config will be used for authenticating a user. If the
-`authetication_string` for an entry is empty, a fallback service (e.g. `other`)
-is used. If a username@host has multiple matching entries, they will all be
-attempted until authentication succeeds or all 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. 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.
 
 PAM service configuration is out of the scope of this document, see
 [The Linux-PAM System Administrators' Guide

Documentation/Getting-Started/Configuration-Guide.md

@@ -597,6 +597,9 @@ Set the directory where the data files used by MariaDB MaxScale are stored.
 Modules can write to this directory and for example the binlogrouter uses this
 folder as the default location for storing binary logs.
 
+This is also the directory where the password encryption key is read from that
+is generated by `maxkeys`.
+
 ```
 datadir=/home/user/maxscale_data/
 ```
@@ -1318,6 +1321,12 @@ default. To enable them, define the timeout in seconds in the service's
 configuration section. A value of zero is interpreted as no timeout, the same
 as if the parameter is not defined.
 
+**Warning:** If a connection is idle for longer than the configured connection
+timeout, it will be forcefully disconnected and a warning will be logged in the
+MaxScale log file. If you are performing long-running maintenance operations
+(e.g. `ALTER TABLE`) either do them with a direct connection to the server or
+set `connection_timeout` to zero before executing them.
+
 Example:
 
 ```

Documentation/Tutorials/Encrypting-Passwords.md

@@ -3,13 +3,16 @@
 There are two options for representing the password, either plain text or
 encrypted passwords may be used. In order to use encrypted passwords a set of
 keys must be generated that will be used by the encryption and decryption
-process. To generate the keys use the `maxkeys` command and pass the name of the
-secrets file in which the keys are stored.
+process. To generate the keys, use the `maxkeys` command.
 
 ```
-maxkeys /var/lib/maxscale/.secrets
+maxkeys
 ```
 
+By default the key file will be generated in `/var/lib/maxscale`. If a different
+directory is required, it can be given as the first argument to the program. For
+more information, see `maxkeys --help`.
+
 Once the keys have been created the `maxpasswd` command can be used to generate
 the encrypted password.
 
@@ -21,6 +24,10 @@ maxpasswd plainpassword
 The username and password, either encrypted or plain text, are stored in the
 service section using the `user` and `password` parameters.
 
+If a custom location was used for the key file, give it as the first argument to
+`maxpasswd` and pass the password to be encrypted as the second argument. For
+more information, see `maxkeys --help`.
+
 Here is an example configuration that uses an encrypted password.
 
 ```
@@ -32,3 +39,7 @@ servers=dbserv1, dbserv2, dbserv3
 user=maxscale
 password=96F99AA1315BDC3604B006F427DD9484
 ```
+
+If the key file is not in the default location, the
+[`datadir`](../Getting-Started/Configuration-Guide.md#datadir) parameter must be
+set to the directory that contains it.