Update the user credential cache documentation

The release notes now mention that the caching is done by the
authenticators, not by the core. It also mentions that only MySQLAuth
implements this functionality.

Added notes to binlogrouter documentation about the changes to the loading
and storing of users.

Cleaned up MySQL-Authenticator document to make it a bit easier to read.

Documentation/Authenticators/MySQL-Authenticator.md

@@ -9,7 +9,10 @@ needs no further configuration to work.
 
 ## Authenticator options
 
-The client authentication module, _MySQLAuth_, supports authenticator options.
+The client authentication module, _MySQLAuth_, supports authenticator
+options. The `authenticator_options` parameter is supported by listeners
+and servers and expects a comma-separated list of key-value pairs. The
+following options contain examples on how to define it.
 
 ### `cache_dir`
 
@@ -17,19 +20,14 @@ The location where the user credential cache is stored. The default value
 for this is `<cache dir>/<service name>/<listener name>/cache/` where
 `<cache dir>` by default is `/var/cache`.
 
+If _cache_dir_ is defined, the user cache file is stored in `<cache
+dir>/`. No additional directories are appended to the _cache_dir_ value.
+
 Each listener has its own user cache where the user credential information
 queried from the backends is stored. This information is used to
 authenticate users if a connection to the backend servers can't be made.
 
-#### Example configuration
-
 ```
-[Read-Write Listener]
-type=listener
-service=Read-Write Service
-protocol=MySQLClient
-port=4006
-authenticator=MySQLAuth
 authenticator_options=cache_dir=/tmp
 ```
 

Documentation/Release-Notes/MaxScale-2.1.0-Release-Notes.md

@@ -47,6 +47,11 @@ For more information about this configuration entry, please see
 
 ### User data cache
 
+The user data cache stores the cached credentials that are used by some router
+modules. In 2.1.0, the authenticator modules are responsible for the persisting
+of the user data cache. Currently, only the MySQLAuth module implements user
+data caching.
+
 The user data loaded from the backend databases is now stored on a per listener
 basis instead of a per service basis. In earlier versions, each service had its own
 cache directory in `/var/cache/maxscale`. This directory contains cached user

Documentation/Routers/Binlogrouter.md

@@ -16,8 +16,21 @@ Binlogrouter is configured with a comma-separated list of key-value pairs. The f
 
 ### `binlogdir`
 
-This parameter allows the location that MariaDB MaxScale uses to store binlog files to be set. If this parameter is not set to a directory name then MariaDB MaxScale will store the binlog files in the directory /var/cache/maxscale/<Service Name>.
-In the binlog dir there is also the 'cache' directory that contains data retrieved from the master during registration phase and the master.ini file which contains the configuration of current configured master.
+This parameter allows the location that MariaDB MaxScale uses to store binlog
+files to be set. If this parameter is not set to a directory name then MariaDB
+MaxScale will store the binlog files in the directory
+/var/cache/maxscale/<Service Name>.  In the binlog dir there is also the 'cache'
+directory that contains data retrieved from the master during registration phase
+and the master.ini file which contains the configuration of current configured
+master.
+
+From 2.1 onwards, the 'cache' directory is stored in the same location as other
+user credential caches. This means that with the default options, the user
+credential cache is stored in /var/cache/maxscale/<Service Name>/<Listener Name>/cache/.
+
+Read the [MySQL Authenticator](../Authenticators/MySQL-Authenticator.md)
+documentation for instructions on how to define a custom location for the user
+cache.
 
 ### `uuid`
 
@@ -52,6 +65,10 @@ This is the user name that MariaDB MaxScale uses when it connects to the master.
 
 This user is the only one available for MySQL connection to MaxScale Binlog Server for administration when master connection is not done yet.
 
+In MaxScale 2.1, the service user injection is done by the MySQLAuth
+authenticator module. Read the [MySQL Authenticator](../Authenticators/MySQL-Authenticator.md)
+documentation for more details.
+
 The user that is used for replication, either defined using the user= option in the router options or using the username and password defined of the service must be granted replication privileges on the database server.
 
 ```