doc: add acl user guide (#4526)

Signed-off-by: jiefenghuang <[email protected]>
juicedata · Mar 18, 2024 · 801c181 · 801c181
1 parent 0aa7ed5
commit 801c181
Show file tree

Hide file tree

Showing 8 changed files with 106 additions and 4 deletions.
diff --git a/docs/en/administration/sync_accounts_between_multiple_hosts.md b/docs/en/administration/sync_accounts_between_multiple_hosts.md
@@ -4,7 +4,7 @@ sidebar_position: 7
 slug: /sync_accounts_between_multiple_hosts
 ---
 
-JuiceFS supports Unix file permission (but not POSIX extended ACL), you can manage permissions by directory or file granularity, just like a local file system.
+JuiceFS supports Unix file permission, you can manage permissions by directory or file granularity, just like a local file system.
 
 To provide users with an intuitive and consistent permission management experience (e.g. the files accessible by user A on host X should be accessible by the same user on host Y), the same user who wants to access JuiceFS should have the same UID and GID on all hosts.
 

diff --git a/docs/en/introduction/comparison/juicefs_vs_glusterfs.md b/docs/en/introduction/comparison/juicefs_vs_glusterfs.md
@@ -28,7 +28,7 @@ The table below provides a quick overview of the differences between GlusterFS a
 | S3 protocol | Supported (but not updated) | Supported |
 | HDFS compatibility | Supported (but not updated) | Supported |
 | CSI Driver | Supported | Supported |
-| POSIX ACLs | Supported | Not supported |
+| POSIX ACLs | Supported | Supported |
 | Cross-cluster replication | Supported | Relies on external service |
 | Directory quotas | Supported | Supported |
 | Snapshots | Supported | Not supported (but supports cloning) |

diff --git a/docs/en/reference/command_reference.md b/docs/en/reference/command_reference.md
@@ -181,6 +181,7 @@ juicefs format sqlite3://myjfs.db myjfs --trash-days=0
 |`--capacity=0`|storage space limit in GiB, default to 0 which means no limit. Capacity will include trash files, if [trash](../security/trash.md) is enabled.|
 |`--inodes=0`|Limit the number of inodes, default to 0 which means no limit.|
 |`--trash-days=1`|By default, delete files are put into [trash](../security/trash.md), this option controls the number of days before trash files are expired, default to 1, set to 0 to disable trash.|
+|`--enable-acl=true` <VersionAdd>1.2</VersionAdd>|enable [POSIX ACL](../security/posix_acl.md)，it is irreversible. |
 
 ### `juicefs config` {#config}
 
@@ -235,6 +236,7 @@ juicefs config redis://localhost --min-client-version 1.0.0 --max-client-version
 |`--min-client-version value` <VersionAdd>1.1</VersionAdd> |minimum client version allowed to connect|
 |`--max-client-version value` <VersionAdd>1.1</VersionAdd> |maximum client version allowed to connect|
 |`--dir-stats` <VersionAdd>1.1</VersionAdd> |enable dir stats, which is necessary for fast summary and dir quota (default: false)|
+|`--enable-acl` <VersionAdd>1.2</VersionAdd>|enable POSIX ACL(irreversible), min-client-version will be set to v1.2|
 
 ### `juicefs quota` <VersionAdd>1.1</VersionAdd> {#quota}
 

diff --git a/docs/en/security/posix_acl.md b/docs/en/security/posix_acl.md
@@ -0,0 +1,53 @@
+---
+sidebar_position: 1
+---
+
+# POSIX ACL
+
+Version 1.2 supports POSIX ACL. For detailed rules, 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)
+
+## Usage
+
+<!-- markdownlint-disable MD044 enhanced-proper-names -->
+
+Currently, once ACL is enabled, it cannot be disabled.  
+Therefore, the --enable-acl flag is associated with the volume.
+
+### Enable ACL for new volumes
+
+```shell
+juicefs format sqlite3://myjfs.db myjfs --enable-acl
+```
+
+### Enable ACl for existing volumes
+
+- Upgrade all old client to v1.2 and remount it.
+- Use the following command with v1.2 client to change the volume configuration.
+
+```shell
+juicefs config sqlite3://myjfs.db --enable-acl
+```
+
+<!-- markdownlint-enable MD044 enhanced-proper-names -->
+
+## Compatibility
+
+- New client versions are compatible with old volume versions.
+- Old client versions are compatible with new volume versions (without ACL enabled).
+
+:::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.
+:::
+
+## Others
+
+- 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.
diff --git a/docs/zh_cn/administration/sync_accounts_between_multiple_hosts.md b/docs/zh_cn/administration/sync_accounts_between_multiple_hosts.md
@@ -4,7 +4,7 @@ sidebar_position: 7
 slug: /sync_accounts_between_multiple_hosts
 ---
 
-JuiceFS 支持 Unix 文件权限（但不支持 POSIX extended ACL），以目录或文件的粒度管理权限。该行为与本地文件系统相同。
+JuiceFS 支持 Unix 文件权限，以目录或文件的粒度管理权限。该行为与本地文件系统相同。
 
 为了让用户获得直观一致的权限管理体验（例如，用户 A 在主机 X 中访问的文件，在主机 Y 中也应该可以用相同的用户身份访问），想要访问 JuiceFS 存储的同一个用户，应该在所有主机上具有相同的 UID 和 GID。
 

diff --git a/docs/zh_cn/introduction/comparison/juicefs_vs_glusterfs.md b/docs/zh_cn/introduction/comparison/juicefs_vs_glusterfs.md
@@ -26,7 +26,7 @@ description: 本文对比 JuiceFS 和 GlusterFS 的架构、元数据管理、
 | S3 协议 | 支持（久未更新） | 支持 |
 | HDFS 兼容性 | 支持（久未更新） | 支持 |
 | CSI 驱动 | 支持 | 支持 |
-| POSIX ACLs | 支持 | 不支持 |
+| POSIX ACLs | 支持 | 支持 |
 | 跨域复制 | 支持 | 依赖外部服务 |
 | 目录配额 | 支持 | 支持 |
 | 快照 | 支持 | 不支持（但支持克隆） |

diff --git a/docs/zh_cn/reference/command_reference.md b/docs/zh_cn/reference/command_reference.md
@@ -181,6 +181,7 @@ juicefs format sqlite3://myjfs.db myjfs --trash-days=0
 |`--capacity=0`|容量配额，单位为 GiB，默认为 0 代表不限制。如果启用了[回收站](../security/trash.md)，那么配额大小也将包含回收站文件。|
 |`--inodes=0`|文件数配额，默认为 0 代表不限制。|
 |`--trash-days=1`|文件被删除后，默认会进入[回收站](../security/trash.md)，该选项控制已删除文件在回收站内保留的天数，默认为 1，设为 0 以禁用回收站。|
+|`--enable-acl=true` <VersionAdd>1.2</VersionAdd>|启用[POSIX ACL](../security/posix_acl.md)，该选项启用后暂不支持关闭。|
 
 ### `juicefs config` {#config}
 
@@ -235,6 +236,7 @@ juicefs config redis://localhost --min-client-version 1.0.0 --max-client-version
 |`--min-client-version value` <VersionAdd>1.1</VersionAdd>|允许连接的最小客户端版本|
 |`--max-client-version value` <VersionAdd>1.1</VersionAdd>|允许连接的最大客户端版本|
 |`--dir-stats` <VersionAdd>1.1</VersionAdd>|开启目录统计，这是快速汇总和目录配额所必需的 (默认值：false)|
+|`--enable-acl` <VersionAdd>1.2</VersionAdd>|开启 POSIX ACL(不支持关闭), 同时允许连接的最小客户端版本会提升到 v1.2|
 
 ### `juicefs quota` <VersionAdd>1.1</VersionAdd> {#quota}
 

diff --git a/docs/zh_cn/security/posix_acl.md b/docs/zh_cn/security/posix_acl.md
@@ -0,0 +1,45 @@
+---
+sidebar_position: 3
+---
+# POSIX ACL
+
+1.2 版本支持 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)
+
+## 使用
+
+<!-- markdownlint-disable MD044 enhanced-proper-names -->
+
+目前 ACL 开启后暂不支持取消，所以--enable-acl flag 与卷关联。
+
+### 新卷创建启用 ACL
+
+```shell
+juicefs format sqlite3://myjfs.db myjfs --enable-acl
+```
+
+### 已有卷启用 ACL
+
+- 所有旧客户端升级到 v1.2, 并且重新 mount 卷
+- 使用 v1.2 版本客户端执行下面指令进行配置
+
+```shell
+juicefs config sqlite3://myjfs.db --enable-acl
+```
+
+<!-- markdownlint-enable MD044 enhanced-proper-names -->
+
+## 兼容
+
+- 新版本客户端兼容老版本卷
+- 老版本客户端兼容 (不开启 ACL 的) 新版本卷
+:::caution 提示
+如果启用 ACL 功能，建议所有客户端都升级。老版本客户端挂载了新卷 (没有开启 ACL), 后续如果卷开启 ACL, 老版本客户端的操作会影响 ACL 的正确性
+:::
+
+## 其他
+
+- 开启 ACL 后，客户端版本要求会提升到 v1.2
+- 开启 ACL 会有额外的性能影响，对于 ACL 变动不频繁的场景，有内存 cache 优化影响不大