From 15fcf7d8814442756317f79a9449d7bafe8440c9 Mon Sep 17 00:00:00 2001 From: Exlany Date: Fri, 19 Sep 2025 14:34:59 +0000 Subject: [PATCH] add ACL doc --- en/guide/config/acl.md | 220 +++++++++++++++++++++++++++++ en/index.md | 5 + guide/config/acl.md | 220 +++++++++++++++++++++++++++++ index.md | 5 + public/.well-known/applinking.json | 9 ++ 5 files changed, 459 insertions(+) create mode 100644 en/guide/config/acl.md create mode 100644 guide/config/acl.md create mode 100644 public/.well-known/applinking.json diff --git a/en/guide/config/acl.md b/en/guide/config/acl.md new file mode 100644 index 0000000..fc7120a --- /dev/null +++ b/en/guide/config/acl.md @@ -0,0 +1,220 @@ +# Easytier ACL Feature Guide 🛡️ + +## 📖 Table of Contents + +1. [Core Concepts](#-core-concepts) +2. [How It Works](#-how-it-works) +3. [Configuration Details](#-configuration-details) +4. [Common Use Case Examples](#-common-use-case-examples) +5. [Best Practices and Notes](#-best-practices-and-notes) + +--- + +## 🧠 Core Concepts + +Understanding the following key concepts is essential for configuring ACL: + +- **ACL (Access Control List)**: A set of rules used to allow or deny network traffic. Easytier's 2.4.0 update introduced IP-based ACL control, and version 2.4.3 added a zero-trust ACL mechanism based on identity groups, making policies more flexible. +- **Chain**: A collection of rules. Chains have types; for example, `chain_type = 1` represents an inbound chain, processing traffic sent to the local machine. +- **Rule**: Defines traffic matching conditions (such as protocol, port, source/target groups) and the action to take upon a match (allow or deny). +- **Group**: A logical identity tag. A node (server, computer, etc.) can declare that it belongs to one or more groups (e.g., `admin`, `database`). +- **Group Declaration**: A node needs to know in advance all the group names it might communicate with and their corresponding shared secrets. The secret is used to verify whether the group membership claimed by other nodes is valid. +- **Priority**: Rules are matched in descending order of priority value. Once traffic matches a rule, its action is executed, and subsequent matching stops. + +--- + +## 🔧 Configuration Details + +ACL configuration must be added to Easytier's configuration file `config.yaml`. + +### 1. Define Groups and Secrets + +This is the most critical step. Each node needs to declare which groups it belongs to in its configuration and configure the shared secrets for all related groups. + +```yaml +# This section defines the groups this node will join (for generating identity proof) +[acl.acl_v1.group] +members = ["admin", "web-server"] # This node's identity: both an administrator and a web server + +# This section defines all groups "known" to this node and their secrets (for verifying peer identities) +[[acl.acl_v1.group.declares]] +group_name = "admin" +group_secret = "super-secret-admin-key" # Please use a more complex key! + +[[acl.acl_v1.group.declares]] +group_name = "web-server" +group_secret = "web-server-secret-key" + +[[acl.acl_v1.group.declares]] +group_name = "database" +group_secret = "database-secret-key" + +[[acl.acl_v1.group.declares]] +group_name = "guest" +group_secret = "guest-secret-key" +``` + +> **⚠️ Important Notes**: +> - `members`: Defines this node's identity. +> - `declares`: Acts as the node's "address book" and must include definitions for all groups in the network that might communicate. The `declares` section must be completely consistent across all nodes. +> - `group_secret`: The cornerstone of security. Must use a strong, unique secret, and all nodes must share the same secret definitions. + +--- + +### 2. Configure Rule Chains + +Rule chains determine how traffic is handled. + +```yaml +# Define an inbound chain +[[acl.acl_v1.chains]] +name = "my_acl_policy" # Chain name +chain_type = 1 # 0: Unspecified, 1: Inbound chain (processes traffic sent to this machine), 2: Outbound (processes traffic sent from this machine), 3: Forwarding (subnet proxy) +description = "My security policy" +enabled = true # Enable this chain +default_action = 2 # Default action: 1(Allow) 2(Deny) +``` + +--- + +### 3. Configure Rules + +Rules are the core of the policy and are defined within chains. + +```yaml +# List of rules within the chain defined above +[[acl.acl_v1.chains.rules]] +name = "allow_admin_rdp" +description = "Allow administrators to RDP to this machine" +priority = 1000 # Priority, higher number means higher priority (0-65535) +action = 1 # Action: 0(No operation) 1(Allow) 2(Deny) +source_groups = ["admin"] # Rule match: source device must belong to the admin group +protocol = 1 # Protocol: 0(Unspecified) 1(TCP) 2(UDP) 3(ICMP) 4(ICMPv6) 5(Any) +ports = ["3389"] # Local allowed port: 3389 (RDP) +enabled = true # Enable this rule + +[[acl.acl_v1.chains.rules]] +name = "deny_guest_to_db" +description = "Deny guests access to the database" +priority = 900 # Lower priority +action = 2 # Action: 0(No operation) 1(Allow) 2(Deny) +source_groups = ["guest"] # Rule match: source device must belong to the guest group +destination_groups = ["database"] # Match when the target device belongs to the database group +enabled = true # Enable the rule +protocol = 1 # TCP protocol +ports = [] # If empty, matches all ports +source_ips = [] # If empty, matches all source IP ranges; format `10.144.144.2/32` +destination_ips = [] # If empty, matches all destination IP ranges +source_ports = [] # If empty, matches all source ports +rate_limit = 0 # Rate limit (bps), 0 = unlimited +burst_limit = 0 # Maximum burst bandwidth (bps) +stateful = true # Enable connection tracking +``` + +--- + +## 🧪 Common Use Case Examples + +### Use Case 1: Minimal Security Group - "Same Secret Allows Access" + +**Goal**: Implement a private network where devices with the same secret can communicate; devices without the secret cannot join. + +**Configuration**: + +```yaml +[acl.acl_v1.group] +members = ["my-net"] # All devices join the same group + +[[acl.acl_v1.group.declares]] +group_name = "my-net" +group_secret = "my-net-secret-key" # All devices use the same secret + +[[acl.acl_v1.chains]] +name = "default_inbound" +chain_type = 1 +enabled = true +default_action = 2 # Deny by default + +# Core rule: Allow all communication within the group +[[acl.acl_v1.chains.rules]] +name = "allow_whole_group" +description = "Allow all traffic within the group" +priority = 1000 +action = 1 +source_groups = ["my-net"] # Source is a group member +destination_groups = ["my-net"] # Destination is a group member +protocol = 1 +enabled = true +``` + +--- + +### Use Case 2: Three-Tier Network Architecture + +**Goal**: Simulate a classic Web-DB architecture, only allowing web servers to access specific ports on the database. + +**Node Configuration**: + +- Web Server: `members = ["web"]` +- Database Server: `members = ["db"]` +- Admin Machine: `members = ["admin"]` + +**ACL Rules on the Database Server**: + +```yaml +[[acl.acl_v1.chains]] +name = "db_server_policy" +chain_type = 1 +enabled = true +default_action = 2 # Deny all connections by default + +# Rule 1: Allow web servers to access the database port +[[acl.acl_v1.chains.rules]] +name = "allow_web_to_mysql" +description = "Allow the web group to access MySQL" +priority = 100 +action = 1 +source_groups = ["web"] +destination_groups = ["db"] # Target is this machine (db group) +protocol = 1 +ports = ["3306"] # Only open MySQL port +enabled = true + +# Rule 2: Allow admins access to all ports (e.g., for management) +[[acl.acl_v1.chains.rules]] +name = "allow_admin_to_all" +description = "Allow administrators access to all services" +priority = 110 # Higher priority than the previous rule +action = 1 +source_groups = ["admin"] +destination_groups = ["db"] # Target is this machine (db group) +protocol = 1 +enabled = true +``` + +--- + +## ✅ Best Practices and Notes + +1. **Secret Management**: + - **Importance**: `group_secret` is the foundation of security. If leaked, attackers can freely join your network. + - **Recommendation**: Use a password generator to create long and complex secrets, and rotate them periodically. + - **Secure Storage**: Do not commit the configuration file to public code repositories. + +2. **Configuration Consistency**: + - Ensure the `[[acl.acl_v1.group.declares]]` section is completely consistent (same group names and secrets) across all nodes in the network. Otherwise, group verification will fail, and the network will not function correctly. + +3. **Debugging Tips**: + - Start with a relaxed policy (`default_action = 1`) and use logs to confirm network connectivity. + - Gradually add deny rules (`action = 2`) to restrict access. + - Finally, change the `default_action` to deny (`2`) to implement a "whitelist" model. + - Make full use of the `description` field to add clear comments for each rule, facilitating future maintenance. + - The `easytier-cli acl stats` command can be used to view ACL statistics. + +4. **Operation Order**: + - After modifying ACL configuration, the Easytier process usually needs to be restarted to take effect. + - Commands like `easytier-core -d --tcp-whitelist port number` can automatically generate simple port whitelist rules, which can serve as a starting point for learning. + +--- + +We hope this document helps you better understand and use Easytier's ACL features! If you have any questions, welcome to discuss them in the community. 🎉 \ No newline at end of file diff --git a/en/index.md b/en/index.md index fbd7d4b..0607dd4 100644 --- a/en/index.md +++ b/en/index.md @@ -72,6 +72,11 @@ features: Langlang Cloud Sponsored Public Server + + + ZONCHA Cloud+ + Sponsored Public Server + ## Sponsor {#sponsor} diff --git a/guide/config/acl.md b/guide/config/acl.md new file mode 100644 index 0000000..31673fe --- /dev/null +++ b/guide/config/acl.md @@ -0,0 +1,220 @@ +# Easytier ACL 功能指南 🛡️ + +## 📖 目录 + +1. [核心概念](#-核心概念) +2. [工作原理](#-工作原理) +3. [配置详解](#-配置详解) +4. [常用场景示例](#-常用场景示例) +5. [最佳实践与注意事项](#-最佳实践与注意事项) + +--- + +## 🧠 核心概念 + +理解以下几个关键概念是配置 ACL 的基础： + +- **ACL（访问控制列表）**：一组规则的集合，用于允许或拒绝网络流量。Easytier 自 2.4.0 版本起支持基于 IP 的 ACL，2.4.3 版本新增基于身份组（Group）的零信任 ACL 机制，策略配置更加灵活。 +- **链（Chain）**：规则的集合。链有不同的类型，例如 `chain_type = 1` 表示入站链，用于处理发送到本机的流量。 +- **规则（Rule）**：定义流量匹配条件（如协议、端口、源/目标组）及匹配后的执行动作（允许或拒绝）。 +- **组（Group）**：一个逻辑上的身份标签。节点（服务器、电脑等）可以声明自己属于一个或多个组（如 `admin`、`database`）。 +- **组声明（Group Declaration）**：节点需预先知道所有可能通信的组名及其对应的共享密钥，密钥用于验证其他节点声明的组成员身份是否有效。 +- **优先级（Priority）**：规则按优先级数值从高到低匹配。一旦流量匹配某条规则，将执行其动作并停止后续匹配。 + +--- + +## 🔧 配置详解 + +ACL 配置需添加到 Easytier 的配置文件 `config.yaml` 中。 + +### 1. 定义组与密钥 + +这是最关键的一步。每个节点需在配置中声明其所属的组，并配置所有相关组的共享密钥。 + +```yaml +# 本节定义本节点要加入的组（用于生成身份证明） +[acl.acl_v1.group] +members = ["admin", "web-server"] # 本节点身份：既是管理员，也是Web服务器 + +# 本节定义本节点“已知”的所有组及其密钥（用于验证对方身份） +[[acl.acl_v1.group.declares]] +group_name = "admin" +group_secret = "super-secret-admin-key" # 请使用更复杂的密钥！ + +[[acl.acl_v1.group.declares]] +group_name = "web-server" +group_secret = "web-server-secret-key" + +[[acl.acl_v1.group.declares]] +group_name = "database" +group_secret = "database-secret-key" + +[[acl.acl_v1.group.declares]] +group_name = "guest" +group_secret = "guest-secret-key" +``` + +> **⚠️ 重要提示**： +> - `members`：定义本节点的身份。 +> - `declares`：相当于节点的“通讯录”，必须包含网络中所有可能通信的组的定义。所有节点的 `declares` 必须完全一致。 +> - `group_secret`：是安全的核心，必须使用高强度、独一无二的密钥，且所有节点共享相同的密钥定义。 + +--- + +### 2. 配置规则链 (Chain) + +规则链决定了如何处理流量。 + +```yaml +# 定义一个入站链 +[[acl.acl_v1.chains]] +name = "my_acl_policy" # 链名称 +chain_type = 1 # 0：未指定，1：入站链（处理发给本机的流量），2：出站（处理本机发出的流量），3：转发（子网代理） +description = "我的安全策略" +enabled = true # 启用此链 +default_action = 2 # 默认动作：1(允许) 2(拒绝) +``` + +--- + +### 3. 配置规则 (Rules) + +规则是策略的核心，定义在链内部。 + +```yaml +# 上面定义的链中的规则列表 +[[acl.acl_v1.chains.rules]] +name = "allow_admin_rdp" +description = "允许管理员通过RDP连接本机" +priority = 1000 # 优先级，数字越大优先级越高（0-65535） +action = 1 # 动作：0(无操作) 1(允许) 2(拒绝) +source_groups = ["admin"] # 规则匹配：源设备必须属于 admin 组 +protocol = 1 # 协议：0(未指定) 1(TCP) 2(UDP) 3(ICMP) 4(ICMPv6) 5(任何) +ports = ["3389"] # 本机允许端口：3389(RDP) +enabled = true # 启用此规则 + +[[acl.acl_v1.chains.rules]] +name = "deny_guest_to_db" +description = "拒绝访客访问数据库" +priority = 900 # 优先级较低 +action = 2 # 动作：0(无操作) 1(允许) 2(拒绝) +source_groups = ["guest"] # 规则匹配：源设备必须属于 guest 组 +destination_groups = ["database"] # 目标设备属于 database 组时匹配 +enabled = true # 启用规则 +protocol = 1 # TCP协议 +ports = [] # 留空，则匹配所有端口 +source_ips = [] # 留空，则匹配所有源IP范围；格式 `10.144.144.2/32` +destination_ips = [] # 留空，则匹配所有目标IP范围 +source_ports = [] # 留空，则匹配所有源端口 +rate_limit = 0 # 速率限制（bps），0 = 无限制 +burst_limit = 0 # 突发的最高带宽（bps） +stateful = true # 启用连接跟踪 +``` + +--- + +## 🧪 常用场景示例 + +### 场景 1：极简安全组 - “密钥相同即放行” + +**目标**：实现一个私有网络，只要设备拥有相同的密钥，就能互通；没有密钥的设备无法接入。 + +**配置**： + +```yaml +[acl.acl_v1.group] +members = ["my-net"] # 所有设备都加入同一个组 + +[[acl.acl_v1.group.declares]] +group_name = "my-net" +group_secret = "my-net-secret-key" # 所有设备使用相同密钥 + +[[acl.acl_v1.chains]] +name = "default_inbound" +chain_type = 1 +enabled = true +default_action = 2 # 默认拒绝 + +# 核心规则：允许组内所有通信 +[[acl.acl_v1.chains.rules]] +name = "allow_whole_group" +description = "允许组内所有流量" +priority = 1000 +action = 1 +source_groups = ["my-net"] # 源是组内成员 +destination_groups = ["my-net"] # 目标是组内成员 +protocol = 1 +enabled = true +``` + +--- + +### 场景 2：三层网络架构 + +**目标**：模拟经典 Web-DB 架构，只允许 Web 服务器访问数据库的特定端口。 + +**节点配置**： + +- Web 服务器：`members = ["web"]` +- 数据库服务器：`members = ["db"]` +- 管理员机器：`members = ["admin"]` + +**数据库服务器上的 ACL 规则**： + +```yaml +[[acl.acl_v1.chains]] +name = "db_server_policy" +chain_type = 1 +enabled = true +default_action = 2 # 默认拒绝所有连接 + +# 规则 1: 允许Web服务器访问数据库端口 +[[acl.acl_v1.chains.rules]] +name = "allow_web_to_mysql" +description = "允许Web组访问MySQL" +priority = 100 +action = 1 +source_groups = ["web"] +destination_groups = ["db"] # 目标是本机（db组） +protocol = 1 +ports = ["3306"] # 只开放MySQL端口 +enabled = true + +# 规则 2: 允许管理员访问所有端口（例如用于管理） +[[acl.acl_v1.chains.rules]] +name = "allow_admin_to_all" +description = "允许管理员访问所有服务" +priority = 110 # 优先级比上一条更高 +action = 1 +source_groups = ["admin"] +destination_groups = ["db"] # 目标是本机（db组） +protocol = 1 +enabled = true +``` + +--- + +## ✅ 最佳实践与注意事项 + +1. **密钥管理**： + - **重要性**：`group_secret` 是安全的基石，一旦泄露，攻击者可随意加入您的网络。 + - **建议**：使用密码生成器创建长且复杂的密钥，并定期更换。 + - **安全存储**：不要将配置文件提交到公共代码仓库。 + +2. **配置一致性**： + - 确保网络中所有节点的 `[[acl.acl_v1.group.declares]]` 部分完全一致（相同的组名和密钥），否则会导致组验证失败，网络不通。 + +3. **调试技巧**： + - 从宽松策略（`default_action = 1`）开始，搭配日志确认网络连通性。 + - 逐步添加拒绝规则（`action = 2`）来限制访问。 + - 最后，改为 `default_action = 2` ，形成“白名单”模式。 + - 充分利用 `description` 字段，为每个规则添加清晰注释，便于后期维护。 + - `easytier-cli acl stats` 命令可查看 ACL 统计信息。 + +4. **操作顺序**： + - 修改 ACL 配置后，通常需要重启 Easytier 进程才能生效。 + - 使用 `easytier-core -d --tcp-whitelist 端口号` 等命令可以自动生成简单的端口白名单规则，可作为学习起点。 + +--- + +希望这份文档能帮助您更好地理解和使用 Easytier 的 ACL 功能！如有任何问题，欢迎在社区讨论。🎉 \ No newline at end of file diff --git a/index.md b/index.md index 46b7666..95986c1 100644 --- a/index.md +++ b/index.md @@ -75,6 +75,11 @@ features: 雨云 赞助的公共服务器 + + + 中云计算 + 赞助的公共服务器 + ## 赞助 {#sponsor} diff --git a/public/.well-known/applinking.json b/public/.well-known/applinking.json new file mode 100644 index 0000000..12aa83e --- /dev/null +++ b/public/.well-known/applinking.json @@ -0,0 +1,9 @@ +{ + "applinking": { + "apps": [ + { + "appIdentifier": "6917581172490635834" + } + ] + } +}