This document describes the following security related features in Alluxio.
- Authentication: If
alluxio.security.authentication.type=SIMPLE(by default), Alluxio file system recognizes the user accessing the service. Having
SIMPLEauthentication is required to use other security features such as authorization. Alluxio also supports other authentication modes like
- Authorization: If
alluxio.security.authorization.permission.enabled=true(by default), Alluxio file system will grant or deny user access based on the requesting user and the POSIX permission model of the files or directories to access. Note that, authentication cannot be
NOSASLas authorization requires user information.
- Auditing: If
alluxio.master.audit.logging.enabled=true, Alluxio file system maintains an audit log for user accesses to file metadata.
See Security specific configuration for different security properties.
alluxio.security.authentication.type is set to
SIMPLE, authentication is enabled.
Before an Alluxio client accesses the service, this client retrieves the user information to report
to Alluxio service in the following order:
- If property
alluxio.security.login.usernameis set on the client, its value will be used as the login user of this client.
- Otherwise, the login user is inferred from the operating system.
After the client retrieves the user information, it will use this user information to connect to the service. After a client creates directories/files, the user information is added into metadata and can be retrieved in CLI and UI.
NOSASL, authentication is disabled. Alluxio
service will ignore the user of the client and no information will be associated to the files or
directories created by this user.
CUSTOM, authentication is enabled. Alluxio clients
alluxio.security.authentication.custom.provider.class which is name of a class
alluxio.security.authentication.AuthenticationProvider to retrieve the user.
This mode is currently experimental and should only be used in tests.
Alluxio file system implements a permissions model for directories and files similar as the POSIX permission model.
Each file and directory is associated with:
- an owner, which is the user of the client process to create the file or directory.
- a group, which is the group fetched from user-groups-mapping service. See User group mapping.
The permissions has three parts:
- owner permission defines the access privileges of the file owner
- group permission defines the access privileges of the owning group
- other permission defines the access privileges of all users that are not in any of above two classes
Each permission has three actions:
- read (r)
- write (w)
- execute (x)
For files, the r permission is required to read the file, and the w permission is required to write the file. For directories, the r permission is required to list the contents of the directory, the w permission is required to create, rename or delete files or directories under it, and the x permission is required to access a child of the directory.
For example, the output of the shell command
ls when authorization is enabled is:
./bin/alluxio fs ls / drwxr-xr-x jack staff 24 PERSISTED 11-20-2017 13:24:15:649 DIR /default_tests_files -rw-r--r-- jack staff 80 NOT_PERSISTED 11-20-2017 13:24:15:649 100% /default_tests_files/BASIC_CACHE_PROMOTE_MUST_CACHE
User group mapping
When user is determined, the list of groups is determined by a group mapping service, configured by
alluxio.security.group.mapping.class. The default implementation is
alluxio.security.group.provider.ShellBasedUnixGroupsMapping, which executes the
command to fetch the group memberships of a given user. There is a caching mechanism for user group
mapping, the mapping data will be cached for 60 seconds by default, this value can be configured by
alluxio.security.group.mapping.cache.timeout, if the value is ‘0’, the cached will be disabled.
alluxio.security.authorization.permission.supergroup defines a super group. Any users
belong to this group are also super users.
Initialized directory and file permissions
The initial creation permission is 777, and the difference between directory and file is 111.
For default umask value 022, the created directory has permission 755 and file has permission 644.
The umask can be set by property
Update directory and file permission model
The owner, group, and permissions can be changed by two ways:
- User application invokes the setAttribute(…) method of
Hadoop API. See File System API.
- CLI command in shell. See chown, chgrp, chmod.
The owner can only be changed by super user. The group and permission can only be changed by super user and file owner.
Alluxio supports audit logging to allow system administrators to track users’ access to file metadata.
The audit log file (
master_audit.log) contains multiple audit log entries, each of which corresponds to an access to file metadata.
The format of Alluxio audit log entry is shown in the table below.
|succeeded||True if the command has succeeded. To succeed, it must also have been allowed.|
|allowed||True if the command has been allowed. Note that a command can still fail even if it has been allowed.|
|ugi||User group information, including username, primary group, and authentication type.|
|ip||Client IP address.|
|cmd||Command issued by the user.|
|src||Path of the source file or directory.|
|dst||Path of the destination file or directory. If not applicable, the value is null.|
|perm||User:group:mask or null if not applicable.|
It is similar to the format of HDFS audit log wiki.
To enable Alluxio audit logging, you need to set the JVM property
Service level encryption is not supported yet, user could encrypt sensitive data at application level, or enable encryption feature at under file system, e.g. HDFS transparent encryption, Linux disk encryption.
It is recommended to start Alluxio master and workers by one same user. Alluxio cluster service composes of master and workers. Every worker needs to RPC with master for some file operations. If the user of a worker is not the same as the master’s, the file operations may fail because of permission check.