Configure the ACL File User Permissions

Details about ACL file permissions using CGE's security mechanisms.

By default, in the absence of an ACL file, users of the CGE database file will fall into one of two categories:

the instance owner (a user who's username matches that of the Linux username of the user who started the CGE Server)
everyone else

As the instance owner, you have all permissions when interacting with the CGE Server. All other authorized users are permitted only to query the database.

This section explains how to set up an ACL file that allows more precise control of access to the database on a per-user basis.

CGE Permissions

CGE uses a hierarchical set of permissions to control the types of requests an authorized user is permitted to make. The following lists the permissions and the requests or actions they control:

data.query - permission to query (read only) the data set
data.update - permission to update (write only) the data set
data.checkpoint - permission to checkpoint (save to storage) the data set
request.nvp - permission to set one or more configuration NVP settings to be effective for the duration of an individual request, if not present, specifying NVP settings causes the request to fail
request.log - permission to modify logging behavior for the duration of an individual request, if not present, logging is unchanged but the request proceeds normally
server.config.nvp.get - permission to read the NVP configuration in effect in the running server
server.config.nvp.set - permission to alter the NVP configuration in effect in the running server for all subsequent requests
server.config.log.get - permission to read the logging configuration in effect in the running server
server.config.log.set - permission to alter the logging configuration in effect in the running server for all subsequent requests
server.config.output.get - permission to read the name of the output directory used by the server to store result files
server.config.output.set - permission to change the output directory used by the server to store result files for all subsequent requests
server.shutdown - permission to shut down the running server

Permissions may be named individually or may be named using a wildcard character ('*') at any level of the hierarchy. A wildcard character all by itself signifies all permissions. Here are some examples of permission sets and their equivalent wild card definitions:

All Permissions : *
data.query,data.update,data.checkpoint : data.*
server.config.nvp.get,server.config.log.get,server.config.output.get : server.*.get or server.config.*.get
server.config.nvp.get,server.config.nvp.set : server.*.nvp.* or *.nvp.*, or server.config.nvp.*

Notice that various more or less specific forms of wildcarding produce the same result with the current set of permissions. In future releases, new permissions might be added that might match one of the less specific wildcard specifications and grant unexpected rights to a given user. It is generally best to use the most specific wildcard form possible to achieve the desired set of permissions so that you do not experience permission creep from release to release. It is also a good idea to review you ACLs with respect to the permissions available in a given release to ensure that no new permissions are being unexpectedly granted.

The ACL File

The ACL file is a file named user_perms.cfg in the data directory of your database. This file, if present, contains the permission assignments for authorized users using your database. For your convenience, this file allows you to group permissions and users using roles, each of which is a named set of permissions containing the permissions needed to carry out a specific related set of database responsibilities, and groups, each of which is a named set of users to be assigned a common set of permissions or roles. The ACL also permits you to specify permissions or roles for individual users by name, and to specify a default set of permissions using the default user name (*). Here is a sample ACL that illustrates all of these elements:

[roles]
# An administrator has all permissions
admin = *
 
# An auditor has the ability to adjust the logging
# behavior of the running CGE Server
auditor = server.config.log.*
 
# A consumer of data is allowed to query the CGE Database
# and provide per-request NVPs because some NVPs impact the
# efficiency / practicality of certain queries.
consumer = data.query,request.nvp
 
# A producer of data is allowed to query, update, and
# checkpoint the CGE Database, and is allowed to set
# per-request NVPs because some NVPs impact the efficiency
# or practicality of certain queries, and some options on
# checkpointing are controlled by NVPs.
producer = data.*,request.nvp
 
[groups]
admins = joe,mary,abdul
auditors = phyllis,jodi,allan
producers = anne,grace,william
 
# A group of users to whom no access is permitted.  This is
# a useful way of temporarily disabling a user while keeping
# that user's authorized keys active.  The group is defined
# here with its member list, but is never assigned any roles
# or permissions. This prevent's these users from being
# treated as default users (allowing default users to have
# more permissions) while ensuring they have no access.
denied_users = wilbur,ginger,ava
 
[permissions]
group:admins = role:admin
group:auditors = role:auditor
group:producers = role:producer
# The user 'david' is an auditor who also needs to be able to
# see what is in the database, so he needs both the auditor and
# consumer role.
david = role:auditor,role:consumer
# The user 'fred' needs to be able to query, but we don't trust
# him with changing per-request NVPs, so he can't do that.
fred = role:auditor,data.query
 
# Everyone else who is not specifically mentioned either by name
# or by group is allowed to be a 'consumer'
* = role:consumer

There are a few things to notice about the above sample ACL. First of all, it is divided into sections of three types:

The roles section contains role definitions
the groups section contains group definitions
the permissions section contains permission assignments to both groups (where the group name is qualified by the group: prefix), and users.

There may be any number of sections of a given type. The aggregate effect of multiple sections of the same type is the same as having one large section of that type containing all of the content of the smaller sections.

The second thing to notice is that comments are permitted in an ACL file. Comments take the form of a '#' character followed by any arbitrary text up to a newline. The comment ends at the newline.

The third thing is not obvious from the example, but the sections, definitions and assignments do not need to be presented in any particular order. As long as the definitions and assignments take place within the appropriate sections and convey an unambiguous intent, the CGE Server will figure out any necessary ordering.

There are some rules about what constitutes unambiguous intent:

A role or group may have at most one definition in the ACL
A group or user may have at most one permission assignment in the ACL
A user may belong to at most one group
A user may not both belong to a group and have a permission assignment
The list of permissions and roles in a permission assignment may contain any arbitrary list of permissions and roles, even repeated permissions or repeated roles
The default (*) user is a default user, not a wildcard user, so assigning permissions or roles to it, at most once, does not violate any of the above rules regarding explicitly named users

If an ACL file is changed while the CGE Server is running, its contents will take effect upon receipt of the next request. This permits on-the-fly changes to the ACL, but it also opens up the possibility of creating a malformed interim ACL while editing or in the process of copying a new ACL into position. In order to replace an ACL safely, it is a good practice to make a copy of the ACL that needs to be edited, then edit the copy and verify it using the cge-test-permissions command, before moving it into place using the mv(1) Linux command. The advantage of using the mv(1) command instead of the cp(1) command is that the rename of the file performed by mv(1) is atomic, so no request can come in while the file is being copied. The risk of a race condition here is tiny, but it could produce surprising effects that cannot be reproduced.

For more information, see the cge-test-permissions(1) and CGE-PERMISSIONS(5) man pages.

ACL File Verification

The cge-test-permissions command allows you to verify the correctness of an ACL without needing to read through the CGE Server log for errors. While an ACL file may reside on any file system accessible by the CGE Server for its ultimate use (e.g. HDFS) , the cge-test-permissions command only has access to files on POSIX compliant (i.e. Linux native) file systems. Since you are most likely to edit your ACL files on a native file system and then copy them to, for example, an HDFS file system, this should not be too much of an inconvenience, but it is important to note that specifying a URL for an ACL filename to cge-test-permissions will result in an error.

Here are a few examples of common uses of cge-test-permissions using the example ACL file shown above:

# Check that the ACL file is correctly formed and unambiguous,
# expecting a silent exit (the exit value will be 0) on success
$ cge-test-permissions perms_example.cfg
 
# Check the definition of the 'auditor' role
$ cge-test-permissions -r auditor perms_example.cfg
Role 'auditor':
        Permissions: server.config.log.get, server.config.log.set
 
# Check the definition and permissions assigned to the 'auditors' group
$ cge-test-permissions -g auditors perms_example.cfg
Group 'auditors':
        Roles:
            auditor [server.config.log.get, server.config.log.set]
        Assigned Permissions: <none>
        Effective Permissions: server.config.log.get, server.config.log.set
        Members: phyllis, jodi, allan
 
# Check the definition of the user 'jodi'
$ cge-test-permissions -u jodi perms_example.cfg
User 'jodi':
        Member of group auditors [server.config.log.get, server.config.log.set]
        Roles: <none>
        Assigned Permissions: <none>
        Effective Permissions: server.config.log.get, server.config.log.set
 
# Check the definition of the user 'fred'
$ cge-test-permissions -u fred perms_example.cfg
User 'fred':
        Member of no group
        Roles:
            auditor [server.config.log.get, server.config.log.set]
        Assigned Permissions: data.query
        Effective Permissions: data.query, server.config.log.get, server.config.log.set
# Check the definition of the denied user 'ava'
$ cge-test-permissions -u ava example_acl
User 'ava':
        Member of group denied_users []
        Roles: <none>
        Assigned Permissions: <none>
        Effective Permissions: <none>

If any of the above commands were run using an ACL with errors or ambiguity in it, the command would have reported errors as it found them, allowing you to correct the errors and re-run the command.

The first example is simple. If no options are given, the command simply verifies that the specified file is acceptable and exits silently if it is okay.

The second example displays the contents of the single role named auditor. Here the name of the role and the permissions that make up that role are displayed.

The third example displays both the definition and the permissions of the group auditors. In this case, the name of the group and the users making up that group are displayed. In addition to that, though, the group also may be assigned some set of roles, and may be assigned some set of explicit permissions. Any roles assigned to this group are displayed, and two different kinds of permissions are displayed. The first set of permissions is the Assigned Permissions these are the permissions that were explicitly assigned to the group by name. The second set of permissions is the Effective Permissions. These are the permissions that result from combining the permissions derived from roles with any permissions explicitly assigned by name. They are the permissions that will actually be used to make an access decision when a member of this group issues a request to the CGE Server.

The fourth example displays information about the user jodi. A user may belong to a group, or be assigned permissions and / or roles explicitly, so all of this is displayed. Here we see that jodi is a member of the group auditors which contributes a set of permissions, but has no explicitly assigned permissions or roles. The Effective Permissions here are the permissions derived from group membership, role assignment and explicit permission assignment. In the case of jodi the effective permissions are derived from the group auditors so they are the same as that group.

The fifth example displays information about fred who has an explicit role assignment and an explicit permission assignment but is not a member of any group. Here we see the role auditor contributes a set of permissions, and there is one permission explicitly assigned to fred. The Effective Permissions in fred's case are the combination of the role permissions and the explicit permissions (no permissions are contributed by a group).

The last example displays information about ava who has had all permission explicitly denied to her by placing her in a group of users who are denied permissions. Notice that she is a member of the group denied_users which has no permissions assigned to it. She has no explicit permissions and no effective permissions.

It is also possible to dump out the complete state (all roles, groups and users) defined by an ACL file using thecge-test-permissions -a command. This produces a lot of output, so it is not shown here, but the output is formatted the way it is shown above.

Once you are satisfied with your ACL file, place it in your data directory and it will take immediate effect.