Client Access Control (ACL)

JuiceFS offers two access control mechanisms: access token and POSIX extended ACL. They offer control on different dimensions, access token dictates who gets to mount (and what is the overall permission of the mount point); and the POSIX ACL handles permission of different users / groups on a single host.

Access token

In JuiceFS, file metadata such as directory, file attributes, timestamps are stored in our metadata services. Clients use access tokens to authenticate against server.

ACL is supported via tokens, users can manage tokens in JuiceFS web console. You can create access control rules using IP range, read / write permission and subdirectory mount restrictions.

When running juicefs mount to mount JuiceFS, or using juicefs auth, a token is needed for authentication. The default token can be found in the file system setting page, you can also create multiple tokens with different ACL and other mount settings.

The default token grants full access to the file system from any IP range. Finer access control can be configured in Access Control tab.

There are two types of tokens, one for client to access file system content, the other for accessing monitoring API.

Client Access Token

Client access token grants client access to file system, while also controlling some client behavior, you can customize the following settings on the Access Control tab in console:

• IP range: Allow access from specified IP range only
• Read / Write Permission
  • Read only: Allow read operations only (e.g. open, read, readdir and etc.)
  • Read, append only: In addition to read operations, allow open file with append option to write, but deny overwrite and truncation of existing content.
  • Read write: Allow all read write operations.
• Mount options
  • Mount subdirectory: Restrict mount subdirectory under this path only, must add --subdir when mounting this file system.
  • Allow background jobs: By default, client executes background jobs such as chunk delete, compaction, and cross-region replication (feature is not scoped by read/write and subdirectory permission). For low bandwidth hosts, disabling background jobs is recommended for better system performance.

warning

The client access token only restricts permission to metadata and is not directly tied to object storage permissions. If you need to restrict read-only access towards your file system, ensure that you use a read-only access key and secret key for the object storage.

API Only Token

JuiceFS exports monitoring metrics of each file system via Prometheus API. API only token grants access only to the monitoring API, and cannot be used to mount JuiceFS.

POSIX Extended ACL

POSIX file systems in Linux supports minimum ACL, which consists of 3 entries that we're well familiar with, called owner, group, other. Above this minimum ACL there's also extended ACL, with which users can assign more sophisticated rules, e.g. set different permission for each individual groups on a single file (read setfacl for more).

JuiceFS supports extended ACL as well, but disabled by default to save some overhead. To enable, add --enable-acl to the mount command.

juicefs mount myjfs /jfs --enable-acl

With extended ACL enabled, don't forget JuiceFS performs UID / GID auto mapping by default. This feature ensures users with the same name (their UIDs might vary) on different nodes are assigned the exact same permission.

Change umask to allow access by other users/groups

umask dictates the default permission for files created by a user. This topic isn't related to JuiceFS, but included as a FAQ.

The default umask is 022 for the root user, which means when files are created, their permission will be 666 - 022 = 644, modifiable to the root user, and readable to other users/groups.

If you wish to assign read/write permission to created files, modify umask like this:

# The leading 0 signifies an octal number
# Once changed to 000, the default permission will be 666
umask 0000