MXS-1354: Make new users backwards compatible

The `add user` and `enable account` commands create fully privileged
administrative users like they did in 2.1. This makes the addition of
read-only users backwards compatible.

Updated and expanded the documentation on administrative interface
users. Added entries into the release notes as well as the upgrading
document about relevant changes between 2.1 and 2.2.

Documentation/Getting-Started/Configuration-Guide.md

@@ -565,8 +565,8 @@ The port where the HTTP admin interface listens on. The default value is port
 #### `admin_auth`
 
 Enable HTTP admin interface authentication using HTTP Basic Access
-authentication. This is not a secure method of authentication but it does add a
-small layer of security. This option is enabled by default.
+authentication. This is not a secure method of authentication without HTTPS but
+it does add a small layer of security. This option is enabled by default.
 
 The admin interface authentication uses the same user as MaxAdmin network
 interface. This means that new users can be added with both MaxAdmin and the

Documentation/REST-API/API.md

@@ -21,6 +21,22 @@ Although JSON does not define a syntax for comments, some of the JSON examples
 have C-style inline comments in them. These comments use `//` to mark the start
 of the comment and extend to the end of the current line.
 
+## Authentication
+
+The MaxScale REST API uses [HTTP Basic Access](https://tools.ietf.org/html/rfc2617#section-2)
+authentication with the MaxScale administrative interface users. The default
+user is `admin:mariadb`, the same as the MaxAdmin network user.
+
+It is highly recommended to enable HTTPS on the MaxScale REST API to make the
+communication between the client and MaxScale secure. Without it, the passwords
+can be intercepted from the network traffic. Refer to the
+[Configuration Guide](../Getting-Started/Configuration-Guide.md#admin_ssl_key) for more
+details on how to enable HTTPS for the MaxScale REST API.
+
+For more details on how administrative interface users are created and managed,
+refer to the [MaxAdmin](../Reference/MaxAdmin.md) documentation as well as the
+documentation of the [users](Resources-User.md) resource.
+
 ## Resources
 
 The MaxScale REST API provides the following resources. All resources conform to
@@ -106,7 +122,12 @@ Acceptable character sets.
 
 #### Authorization
 
-Credentials for authentication.
+Credentials for authentication. This header should consist of a HTTP Basic
+Access authentication type payload which is the base64 encoded value of the
+username and password joined by a colon e.g. `Base64("maxuser:maxpwd")`. The
+REST API uses the same users as the MaxAdmin interface. For more details about
+MaxScale administrative users, refer to the [MaxAdmin](../Reference/MaxAdmin.md)
+documentation.
 
 #### Content-Type
 

Documentation/Reference/MaxAdmin.md

@@ -118,6 +118,31 @@ passing commands on the MaxAdmin command line itself.
 
 # Working With Administration Interface Users
 
+Both MaxAdmin and the newly added REST API use the administrative users of
+MaxScale. The network type administrative users are used by the REST API as well
+as MaxAdmin when it is configured to use a network listener. Linux account type
+users are only used by MaxAdmin when the UNIX Domain Socket interface is
+activated.
+
+## Administrative and Read-only Users
+
+Administrative users can perform all operations that MaxScale offers. This
+includes both read-only operations as well as operations that modify the
+internal state of MaxScale or its modules.
+
+The default user for both the network and the UNIX domain socket
+interfaces is an administrative user. This user will be removed once the
+first administrative user of that type is created. The default user for
+the network interface is `admin` with the password `mariadb`. The default
+user for the UNIX domain socket interface is `root`.
+
+Users that can only perform read-only operations are created with `add
+readonly-user` command. These users can only perform operations that fetch data
+and do not modify the state of MaxScale.
+
+To convert administrative users to read-only users, delete the old
+administrative user and create it as a read-only user.
+
 ## What Users Have Been Defined?
 
 In order to see the Linux users for whom MaxAdmin usage has been enabled and any
@@ -179,9 +204,6 @@ User maxscale-admin has been successfully added.
 MaxScale>
 ```
 
-Note that there is no difference in rights between an enabled Linux account and
-an explicitly created user.
-
 ## Delete A User
 
 To remove a user the command _remove user_ is used and it is invoked with the
@@ -194,7 +216,18 @@ MaxScale>
 ```
 
 Note that it is possible to remove the current user, but that will only affect
-the next attempt to use MaxAdmin.
+the next attempt to use MaxAdmin. The last administrative account cannot be
+removed.
+
+## Creating Read-only Users
+
+Currently, the `list` and `show` type commands are the only operations that
+read-only users can perform.
+
+To create a read-only network user, use the `add readonly-user` command. To
+enable a local Linux account as a read-only user, use the `enable
+readonly-account` command. Both administrative and read-only users can be
+deleted with the `remove user` and `disable account` commands.
 
 # Command Line Switches
 

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

@@ -17,6 +17,19 @@ Significant whitespace in object names is now deprecated. All object names
 squeezing repeating whitespace and replacing it with hyphens. If any
 object name conversions take place, a warning will be logged.
 
+### Read-only Administrative Users
+
+Users that can only perform read-only operations can be created with `add
+readonly-user` and `enable readonly-account` commands.  To convert
+administrative users to read-only users, delete the old administrative user and
+create it as a read-only user.
+
+For more information about administrative interface users, refer to the
+[MaxAdmin](../Reference/MaxAdmin.md) documentation.
+
+**Note:** Old users from pre-2.2 MaxScale versions will be converted to
+administrative users that have full access to all commands.
+
 ### MaxAdmin
 
 The `remove user` command now only expects one parameter, the username.

Documentation/Upgrading/Upgrading-To-MaxScale-2.2.md

@@ -12,6 +12,12 @@ For a complete list of changes in MaxScale 2.2.0, refer to the
 Before starting the upgrade, we recommend you back up your current configuration
 file.
 
+### Administrative Users
+
+The file format for the administrative users used by MaxScale has been
+changed. Old style files are automatically upgraded and a backup of the old file is
+stored in `/var/lib/maxscale/passwd.backup`.
+
 ### Regular Expression Parameters
 
 Modules may now use a built-in regular expression string parameter type instead

server/modules/routing/debugcli/debugcmd.c

@@ -762,8 +762,8 @@ struct subcommand enableoptions[] =
     {
         "account",
         1, 1,
-        enable_account,
-        "Activate a Linux user account for read-only MaxAdmin use",
+        enable_admin_account,
+        "Activate a Linux user account for administrative MaxAdmin use",
         "Usage: enable account USER\n"
         "\n"
         "Parameters:\n"
@@ -773,10 +773,10 @@ struct subcommand enableoptions[] =
         {ARG_TYPE_STRING}
     },
     {
-        "admin-account",
+        "readonly-account",
         1, 1,
-        enable_admin_account,
-        "Activate a Linux user account for administrative MaxAdmin use",
+        enable_account,
+        "Activate a Linux user account for read-only MaxAdmin use",
         "Usage: enable account USER\n"
         "\n"
         "Parameters:\n"
@@ -928,8 +928,8 @@ struct subcommand pingoptions[] =
 struct subcommand addoptions[] =
 {
     {
-        "user", 2, 2, inet_add_user,
-        "Add a read-only account for using maxadmin over the network",
+        "user", 2, 2, inet_add_admin_user,
+         "Add an administrative account for using maxadmin over the network",
         "Usage: add user USER PASSWORD\n"
         "\n"
         "Parameters:\n"
@@ -940,15 +940,15 @@ struct subcommand addoptions[] =
         {ARG_TYPE_STRING, ARG_TYPE_STRING}
     },
     {
-        "admin", 2, 2, inet_add_admin_user,
-        "Add an administrative account for using maxadmin over the network",
+        "readonly-user", 2, 2, inet_add_user,
+        "Add a read-only account for using maxadmin over the network",
         "Usage: add user USER PASSWORD\n"
         "\n"
         "Parameters:\n"
         "USER     User to add\n"
         "PASSWORD Password for the user\n"
         "\n"
-        "Example: add user admin-bob somepass",
+        "Example: add user bob somepass",
         {ARG_TYPE_STRING, ARG_TYPE_STRING}
     },
     {