Skip to main content

UID / GID Auto Map

JuiceFS supports POSIX compatible ACL to manage permissions in the granularity of directory or file. The behavior is close to a local file system. One thing differentiating JuiceFS is that it allows shared access among multiple hosts. In order to make the permission experience intuitive to user (e.g. the files accessible by user A in host X should be accessible in host Y with the same user), JuiceFS provides name based UID / GID auto mapping.

TL;DR

Users of the same name will have their UID / GID mapped to the same internal ID in meta server for the files or directory owned. The internal ID will be automatically converted to the matched UID / GID when JuiceFS is mounted in a host.

Example

Create user juicefs with UID 1001 on an Ubuntu host X, mount JuiceFS to /jfs and create a new directory juicefs@ubuntu.

[ubuntu]# useradd -m -G sudo -u 1001 juicefs
[ubuntu]# id juicefs
uid=1001(juicefs) gid=1001(juicefs) groups=1001(juicefs),27(sudo)
[ubuntu]# su juicefs
[ubuntu]$ mkdir /jfs/juicefs@ubuntu

Create user with the same name juicefs with UID 2002 on another Centos host Y, mount JuiceFS to /jfs and create a directory juicefs@centos

[centos]# useradd -m -G wheel -u 2002 juicefs
[centos]# id juicefs
uid=2002(juicefs) gid=2002(juicefs) groups=2002(juicefs),10(wheel)
[centos]# su juicefs
[centos]$ mkdir /jfs/juicefs@centos

When listing the owner of the file with ls -l, both hosts show juicefs as expected.

[ubuntu]$ ls -l /jfs
drwxr-xr-x 2 juicefs juicefs 4096 Aug 22 13:02 juicefs@centos
drwxrwxr-x 3 juicefs juicefs 8192 Aug 22 12:35 juicefs@ubuntu
[centos]$ ls -l /jfs
drwxr-xr-x. 2 juicefs juicefs 4096 Aug 22 13:02 juicefs@centos
drwxrwxr-x. 3 juicefs juicefs 8192 Aug 22 12:35 juicefs@ubuntu

Internals

The numeric value of UID and GID can be inspected with ls -n

The output shows that the directory juicefs@centos owned by UID 2002 in Centos, is mapped to UID 1001 in Ubuntu:

[ubuntu]$ ls -n /jfs
drwxr-xr-x 2 1001 1001 4096 Aug 22 13:02 juicefs@centos
drwxrwxr-x 3 1001 1001 8192 Aug 22 12:35 juicefs@ubuntu

While the directory juicefs@ubuntu owned by UID 1001 in Ubuntu is mapped to UID 2002 in Centos:

[centos]$ ls -n /jfs
drwxr-xr-x. 2 2002 2002 4096 Aug 22 13:02 juicefs@centos
drwxrwxr-x. 3 2002 2002 8192 Aug 22 12:35 juicefs@ubuntu

When JuiceFS is mounted, a hash mapping from user and group names to internal ID will be created. If the internal ID of a file entry is found in the mapping, it will be converted to the corresponding user or group. If not, use the internal ID.

In this example, if juicefs user is deleted, the internal ID can be observed after remounting the file system:

# userdel juicefs
# umount /jfs
# ./juicefs mount $JFS_NAME /jfs
# ls -l /jfs
drwxr-xr-x. 2 27055 27055 4096 Aug 22 13:02 juicefs@centos
drwxrwxr-x. 3 27055 27055 8192 Aug 22 12:35 juicefs@ubuntu

Caveats

By default, JuiceFS will map user and group names to a reserved segment for internal ID. Avoid using UID > 10000 to reduce the chance of collision. To disable auto map, please contact support by clicking the chat icon in the bottom left.