UID/GID Auto Map
JuiceFS supports POSIX extended ACL, allowing you to manage permissions at both the directory and file levels, just like a local file system. Simply put, users with the same name will have their UID/GID mapped to the same internal ID in the JuiceFS metadata server for the files they own. This internal ID is automatically converted to the matched UID/GID when JuiceFS is mounted in a host.
By default, JuiceFS maps user and group names to a reserved segment for internal IDs. To minimize conflicts, avoid using UIDs greater than 10,000.
If you want to disable the auto map feature, contact the JuiceFS team to schedule this change. After it is disabled, you may need to run chown on all affected files.
Example
Create a user named juicefs with UID 1001 on an Ubuntu host (Host X), mount JuiceFS to /jfs, and create a new directory named 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
On another CentOS host (Host Y), create a user with the same name juicefs, but with UID 2002. 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
Check UID/GID
You can inspect the numeric UID and GID with ls -n. For example, in Ubuntu, the directory juicefs@centos, owned by UID 2002 in CentOS, is mapped to UID 1001:
[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
On CentOS, the directory juicefs@ubuntu, owned by UID 1001 in Ubuntu, is mapped to UID 2002:
[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 IDs is created. If the internal ID of a file entry is found in the mapping, it is converted to the corresponding user or group. If not, the internal ID is used.
In this example, if the juicefs user is deleted, you will see the internal ID after remounting the file system:
$ userdel juicefs
$ umount /jfs
$ juicefs mount $VOL_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
UID/GID inconsistency
Different hosts may be configured with different users. If you mount JuiceFS in a host that does not have a certain user, mapping could fail and display a very large UID/GID instead, causing inconsistency. This issue is more likely to occur in environments where a host mount point is used in a container, because the UID specified in the container may not exist on the host system. This could cause file system access to fail with "no permission" errors.
To avoid this issue, choose one of the following:
- Use the same set of users across all hosts that mount JuiceFS, make sure UID/GID mapping works.
- Contact the JuiceFS team to disable UID/GID mapping for your file system. After disabling the mapping, you may need to manually modify and manage file permissions.
