From 07ba7a51aad682f300be8bf4194b091bdb2e278c Mon Sep 17 00:00:00 2001 From: Herald Yu Date: Sun, 28 Apr 2024 10:06:21 +0800 Subject: [PATCH] Docs: update posix_acl.md (#4796) Co-authored-by: jiefenghuang --- docs/en/security/posix_acl.md | 62 ++++++++++++++++---------------- docs/zh_cn/security/posix_acl.md | 56 ++++++++++++++++------------- 2 files changed, 63 insertions(+), 55 deletions(-) diff --git a/docs/en/security/posix_acl.md b/docs/en/security/posix_acl.md index 2488a81df900..110b6baacb61 100644 --- a/docs/en/security/posix_acl.md +++ b/docs/en/security/posix_acl.md @@ -1,54 +1,54 @@ --- +title: POSIX ACL +description: This article introduces the POSIX ACL feature supported by JuiceFS and how to enable and use ACL permissions. sidebar_position: 1 --- -# POSIX ACL +POSIX ACL (Portable Operating System Interface for Unix - Access Control List) is a type of access control mechanism in Unix-like operating systems that allows for finer-grained control over file and directory access permissions. -Version 1.2 supports POSIX ACL. For detailed rules, please refer to: +## Versions and Compatibility Requirements -- [POSIX Access Control Lists on Linux](https://www.usenix.org/legacy/publications/library/proceedings/usenix03/tech/freenix03/full_papers/gruenbacher/gruenbacher_html/main.html) -- [setfacl](https://linux.die.net/man/1/setfacl) +* JuiceFS supports POSIX ACL from version 1.2 onwards; +* All versions of the client can mount volumes without ACL enabled, regardless of whether they were created by a new or old version of the client; +* Once ACL is enabled, it cannot be disabled; therefore, the `--enable-acl` option is tied to the volume. -## Usage +:::caution +If you plan to use ACL functionality, it is recommended to upgrade all clients to the latest version to avoid potential issues with older versions affecting the accuracy of ACLs. +::: - +## Enabling ACL -Currently, once ACL is enabled, it cannot be disabled. -Therefore, the --enable-acl flag is associated with the volume. +As mentioned earlier, you can enable ACL when creating a new volume or on an existing volume using a new version of the client. -### Enable ACL for new volumes +### Creating a New Volume and Enabling ACL ```shell -juicefs format sqlite3://myjfs.db myjfs --enable-acl +juicefs format --enable-acl sqlite3://myjfs.db myjfs ``` -### Enable ACl for existing volumes +### Enabling ACL on an Existing Volume -- Upgrade all old client to v1.2 and remount it. -- Use the following command with v1.2 client to change the volume configuration. +Use the `config` command to enable ACL functionality on an existing volume: -```shell -juicefs config sqlite3://myjfs.db --enable-acl +``` +juicefs config --enable-acl sqlite3://myjfs.db ``` - +## Usage -## Compatibility +To set ACL permissions for a file or directory, you can use the `setfacl` command, for example: -- New client versions are compatible with old volume versions. -- Old client versions are compatible with new volume versions (without ACL enabled). +``` +setfacl -m u:alice:rw- /mnt/jfs/file +``` -:::caution Note -If ACL is enabled, it is recommended that all clients to be upgraded. -If an old client mounts a new volume (without ACL enabled), -and ACL is subsequently enabled on the volume, -operations by the old client may impact the correctness of ACL. -::: +For more detailed rules and guidelines on POSIX ACLs, please refer to: + +* [POSIX Access Control Lists on Linux](https://www.usenix.org/legacy/publications/library/proceedings/usenix03/tech/freenix03/full_papers/gruenbacher/gruenbacher_html/main.html) +* [setfacl](https://linux.die.net/man/1/setfacl) +* [JuiceFS ACL Functionality: A Detailed Explanation of Fine-Grained Permission Control](https://juicefs.com/en/blog/release-notes/juicefs-12-beta-1) -## Others +## Notes -- ACL permission checks are supported only in Linux kernel 4.9 and higher versions. You can refer to this [documentation](https://lkml.iu.edu/hypermail/linux/kernel/1610.0/01531.html) for more details. -- Enabling ACL increases the minimum client version requirement to v1.2. -- Enabling ACL may have additional performance implications. -For scenarios with infrequent ACL changes, -the impact is minimal with memory cache optimization. +* ACL permission checks require a [Linux kernel 4.9](https://lkml.iu.edu/hypermail/linux/kernel/1610.0/01531.html) or later; +* Enabling ACL will have an additional performance impact. However, due to memory cache optimization, most usage scenarios experience relatively low performance degradation. diff --git a/docs/zh_cn/security/posix_acl.md b/docs/zh_cn/security/posix_acl.md index 4b75c1a70e2c..70664355650d 100644 --- a/docs/zh_cn/security/posix_acl.md +++ b/docs/zh_cn/security/posix_acl.md @@ -1,46 +1,54 @@ --- +title: POSIX ACL +description: 本文介绍了 JuiceFS 支持的 POSIX ACL 功能，以及如何启用和使用 ACL 权限。 sidebar_position: 3 --- -# POSIX ACL -1.2 版本支持 POSIX ACL, 详细规则参考 +POSIX ACL（Portable Operating System Interface for Unix - Access Control List）是 Unix-like 操作系统中的一种访问控制机制，可以对文件和目录的访问权限进行更细粒度的控制。 -- [POSIX Access Control Lists on Linux](https://www.usenix.org/legacy/publications/library/proceedings/usenix03/tech/freenix03/full_papers/gruenbacher/gruenbacher_html/main.html) -- [setfacl](https://linux.die.net/man/1/setfacl) +## 版本及兼容性要求 -## 使用 +- JuiceFS 从 v1.2 版本开始支持 POSIX ACL； +- 所有版本客户端都可以挂载没有开启 ACL 的卷，不论这些卷是由新版本客户端创建的还是由旧版本客户端创建的； +- ACL 开启后暂不支持取消，因此 `--enable-acl` 选项是关联到卷的。 - +:::caution 提示 +如果计划使用 ACL 功能，建议将所有客户端升级的最新版，避免旧版本客户端影响 ACL 的正确性。 +::: -目前 ACL 开启后暂不支持取消，所以--enable-acl flag 与卷关联。 +## 启用 ACL -### 新卷创建启用 ACL +如前所述，可以用新版客户端在创建新卷时开启 ACL，也可以用新版客户端在已创建的卷上开启 ACL。 + +### 创建新卷并开启 ACL ```shell -juicefs format sqlite3://myjfs.db myjfs --enable-acl +juicefs format --enable-acl sqlite3://myjfs.db myjfs ``` -### 已有卷启用 ACL +### 在已有卷上开启 ACL -- 所有旧客户端升级到 v1.2, 并且重新 mount 卷 -- 使用 v1.2 版本客户端执行下面指令进行配置 +使用 `config` 命令为一个已创建的卷开启 ACL 功能： ```shell -juicefs config sqlite3://myjfs.db --enable-acl +juicefs config --enable-acl sqlite3://myjfs.db ``` - +## 使用方法 -## 兼容 +为一个文件或目录设置 ACL 权限，可以使用 `setfacl` 命令，例如： -- 新版本客户端兼容老版本卷 -- 老版本客户端兼容 (不开启 ACL 的) 新版本卷 -:::caution 提示 -如果启用 ACL 功能，建议所有客户端都升级。老版本客户端挂载了新卷 (没有开启 ACL), 后续如果卷开启 ACL, 老版本客户端的操作会影响 ACL 的正确性 -::: +```shell +setfacl -m u:alice:rw- /mnt/jfs/file +``` + +更多关于 POSIX ACL 的详细规则，请参考： + +- [POSIX Access Control Lists on Linux](https://www.usenix.org/legacy/publications/library/proceedings/usenix03/tech/freenix03/full_papers/gruenbacher/gruenbacher_html/main.html) +- [setfacl](https://linux.die.net/man/1/setfacl) +- [JuiceFS ACL 功能全解析，更精细的权限控制](https://juicefs.com/zh-cn/blog/release-notes/juicefs-v12-beta-1-acl) -## 其他 +## 注意事项 -- 开启 ACL 后，需要[Linux kernel 4.9](https://lkml.iu.edu/hypermail/linux/kernel/1610.0/01531.html)及以上版本，才支持 ACL 权限检测 -- 开启 ACL 后，客户端版本要求会提升到 v1.2 -- 开启 ACL 会有额外的性能影响，对于 ACL 变动不频繁的场景，有内存 cache 优化影响不大 +- ACL 权限检测需要 [Linux kernel 4.9](https://lkml.iu.edu/hypermail/linux/kernel/1610.0/01531.html) 及以上版本； +- 启用 ACL 会有额外的性能影响。但因为有内存缓存优化，大部分使用场景性能损耗都较低，可参考[压测结果](https://juicefs.com/zh-cn/blog/release-notes/juicefs-v12-beta-1-acl#03-%E6%80%A7%E8%83%BD)。