From 6934d56056629c14542f3c83e80d0a595cc3303b Mon Sep 17 00:00:00 2001 From: silverwind Date: Wed, 30 Sep 2026 11:42:29 +0000 Subject: [PATCH] docs: document egress modes and host lists (#557) Documents the settings changed by https://github.com/go-gitea/gitea/pull/39426: `EGRESS_MODE`, the `[migrations]` `ALLOWED_HOST_LIST`/`BLOCKED_HOST_LIST` replacing `ALLOWED_DOMAINS`, `BLOCKED_DOMAINS` and `ALLOW_LOCALNETWORKS`, and the host list syntax with ports, CGNAT and reserved addresses. Also fixes the `socks://` examples, Go only speaks `socks5://`. _Written by Claude._ --------- Co-authored-by: Lunny Xiao Co-authored-by: TheFox0x7 Reviewed-on: https://gitea.com/gitea/docs/pulls/557 Reviewed-by: Lunny Xiao Co-authored-by: silverwind --- docs/administration/config-cheat-sheet.md | 40 +++++++++++++------ .../administration/config-cheat-sheet.md | 20 +++++----- .../administration/config-cheat-sheet.md | 20 +++++----- .../administration/config-cheat-sheet.md | 20 +++++----- .../administration/config-cheat-sheet.md | 20 +++++----- .../administration/config-cheat-sheet.md | 40 +++++++++++++------ 6 files changed, 92 insertions(+), 68 deletions(-) diff --git a/docs/administration/config-cheat-sheet.md b/docs/administration/config-cheat-sheet.md index 5907d8ba..a21a734e 100644 --- a/docs/administration/config-cheat-sheet.md +++ b/docs/administration/config-cheat-sheet.md @@ -646,14 +646,24 @@ And the following unique queues: - `SUCCESSFUL_TOKENS_CACHE_SIZE`: **20**: Cache successful token hashes. API tokens are stored in the DB as pbkdf2 hashes however, this means that there is a potentially significant hashing load when there are multiple API operations. This cache will store the successfully hashed tokens in a LRU cache as a balance between performance and security. - `DISABLE_QUERY_AUTH_TOKEN`: **false**: Reject API tokens sent in URL query string (Accept Header-based API tokens only). This setting will default to `true` in Gitea 1.23 and be deprecated in Gitea 1.24. - `TWO_FACTOR_AUTH`: **_empty_**: set to enforced to enforce two factor authentication. Only available in Gitea 1.24 and later. -- `ALLOWED_HOST_LIST`: **external**: Webhook and oauth2 clients can only call allowed hosts for security reasons. Comma separated list. +- `EGRESS_MODE`: **lax**: Egress mode toggles between strictness of outgoing requests: + - `lax` requires addresses to be allowed only if they are in private ranges, it allows all public ones + - `strict` requires an explicit allow of all addresses +- `ALLOWED_HOST_LIST`: **_empty_**: Webhook and oauth2 clients can only call allowed hosts for security reasons. Comma separated list, eg: `192.168.1.0/24:3000`, `[2001:db8::/32]:9090`, `*.mydomain.com:[80|443]` - Built-in networks: - `loopback`: 127.0.0.0/8 for IPv4 and ::1/128 for IPv6, localhost is included. - - `private`: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) and RFC 4193 (FC00::/7). Also called LAN/Intranet. - - `external`: A valid non-private unicast IP, you can access all hosts on public internet. - - `*`: All hosts are allowed. - - CIDR list: `1.2.3.0/8` for IPv4 and `2001:db8::/32` for IPv6 - - Wildcard hosts: `*.mydomain.com`, `192.168.100.*` + - `private`: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), RFC 4193 (FC00::/7) and RFC 6598 CGNAT (100.64.0.0/10). Also called LAN/Intranet. + - CIDR list: `1.2.3.0/8`, `2001:db8::/32`, and with a port `[2001:db8::/32]:9090` (IPv6 addresses and CIDRs need brackets when a port is given) + - Host matching: `example.com` matches the host and any subdomain, dot-anchored so `notexample.com` never matches. `*.example.com` and `.example.com` match only subdomains, the apex itself is excluded. IDN names must be given as punycode. + - All addresses can have ports specified. Accepted port specs: + - a single port: `192.168.1.0/24:3000` + - a range, both bounds inclusive: `*.mydomain.com:3000-3010` + - a bracketed set of ports and ranges, `|` separated: `*.mydomain.com:[80|443|3000-3010]` + - all ports: `*.mydomain.com:*` + - A portless entry covers all ports in `lax` mode, only 80 and 443 in `strict` mode + - Port specs apply only where the list is consulted: in `lax` mode that is private, loopback and CGNAT targets alone, public targets are allowed on every port whatever the list says. In `strict` mode every target is checked, so ports restrict public hosts too. + - Reserved addresses like link-local and cloud metadata are denied + - This list is enforced on direct connections only. When an HTTP proxy is configured, restricting the proxied target is the proxy server's responsibility. ## Audit (`audit`) @@ -807,9 +817,11 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type - `DELIVER_TIMEOUT`: **5**: Delivery timeout (sec) for shooting webhooks. - `SKIP_TLS_VERIFY`: **false**: Allow insecure certification. - `PAGING_NUM`: **10**: Number of webhook history events that are shown in one page. -- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https//, socks://, blank will follow environment http_proxy/https_proxy. If not given, will use global proxy setting. +- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https://, socks5://, blank will follow environment http_proxy/https_proxy. If not given, will use global proxy setting. - `PROXY_HOSTS`: **_empty_`**: Comma separated list of host names requiring proxy. Glob patterns (*) are accepted; use ** to match all hosts. If not given, will use global proxy setting. +When a proxy is configured, Gitea does not enforce `[security]` `ALLOWED_HOST_LIST` on the proxied target, the proxy server is expected to restrict it. + ## Mailer (`mailer`) :::warning @@ -1427,11 +1439,13 @@ in this mapping or the filetype using heuristics. - `MAX_ATTEMPTS`: **3**: Max attempts per http/https request on migrations. - `RETRY_BACKOFF`: **3**: Backoff time per http/https request retry (seconds) -- `ALLOWED_DOMAINS`: **_empty_**: Domains allowlist for migrating repositories, default is blank. It means external hosts will be allowed. Multiple domains could be separated by commas. Wildcard is supported: `github.com, *.github.com`. -- `BLOCKED_DOMAINS`: **_empty_**: Domains blocklist for migrating repositories, default is blank. Multiple domains could be separated by commas. When `ALLOWED_DOMAINS` is not blank, this option has a higher priority to deny domains. Wildcard is supported. -- `ALLOW_LOCALNETWORKS`: **false**: Allow private addresses defined by RFC 1918, RFC 1122, RFC 4632 and RFC 4291. If a domain is allowed by `ALLOWED_DOMAINS`, this option will be ignored. +- `EGRESS_MODE`: **lax**: Mode toggles between strictness of scanning outgoing requests, same format as `EGRESS_MODE` in [`security`](#security-security). +- `ALLOWED_HOST_LIST`: **_empty_**: Hosts migrations and mirrors may call, same format as `ALLOWED_HOST_LIST` in [`security`](#security-security). Private and loopback addresses need a builtin or CIDR entry. When unset, the deprecated `ALLOWED_DOMAINS` entries apply on every port with `strict` as the default mode, and the deprecated `ALLOW_LOCALNETWORKS` adds `private, loopback`. +- `BLOCKED_HOST_LIST`: **_empty_**: Hosts migrations and mirrors may never call, portless entries cover all ports. - `SKIP_TLS_VERIFY`: **false**: Allow skip tls verify +These lists are enforced on direct connections only. When a proxy is configured (`[proxy]`, `[git.config]` `http.proxy` or the environment), restricting the proxied target is the proxy server's responsibility. + ## Federation (`federation`) - `ENABLED`: **false**: Enable/Disable federation capabilities @@ -1666,14 +1680,16 @@ is `data/repo-archive` and the default of `MINIO_BASE_PATH` is `repo-archive/`. ## Proxy (`proxy`) - `PROXY_ENABLED`: **false**: Enable the proxy if true, all requests to external via HTTP will be affected, if false, no proxy will be used even environment http_proxy/https_proxy -- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https//, socks://, blank will follow environment http_proxy/https_proxy +- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https://, socks5://, blank will follow environment http_proxy/https_proxy - `PROXY_HOSTS`: **_empty_**: Comma separated list of host names requiring proxy. Glob patterns (*) are accepted; use ** to match all hosts. +When a proxy is configured, Gitea does not enforce the egress lists (`[security]`, `[migrations]`) on the proxied target, the proxy server is expected to restrict it. + i.e. ```ini PROXY_ENABLED = true -PROXY_URL = socks://127.0.0.1:1080 +PROXY_URL = socks5://127.0.0.1:1080 PROXY_HOSTS = *.github.com ``` diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/current/administration/config-cheat-sheet.md b/i18n/zh-cn/docusaurus-plugin-content-docs/current/administration/config-cheat-sheet.md index 88ce6de7..86bb1537 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-docs/current/administration/config-cheat-sheet.md +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/current/administration/config-cheat-sheet.md @@ -681,17 +681,16 @@ Gitea 创建以下非唯一队列： - `QUEUE_LENGTH`: **1000**: 钩子任务队列长度。编辑此值时要小心。 - `DELIVER_TIMEOUT`: **5**: 发送 Webhook 的交付超时时间（秒）。 -- `ALLOWED_HOST_LIST`: **external**: 出于安全原因，Webhook 仅能调用允许的主机。以逗号分隔的列表。 +- `ALLOWED_HOST_LIST`: **_empty_**: 出于安全原因，Webhook 仅能调用允许的主机。以逗号分隔的列表。在默认的 `[security]` `EGRESS_MODE = lax` 下仅限制私有地址。 - 内置网络： - `loopback`：IPv4 的 127.0.0.0/8 和 IPv6 的 ::1/128，包括 localhost。 - - `private`：RFC 1918（10.0.0.0/8，172.16.0.0/12，192.168.0.0/16）和 RFC 4193（FC00::/7）。也称为 LAN/Intranet。 - - `external`：一个有效的非私有单播 IP，您可以访问公共互联网上的所有主机。 - - `*`：允许所有主机。 + - `private`：RFC 1918（10.0.0.0/8，172.16.0.0/12，192.168.0.0/16）、RFC 4193（FC00::/7）和 RFC 6598 CGNAT（100.64.0.0/10）。也称为 LAN/Intranet。 - CIDR 列表：IPv4 的 `1.2.3.0/8` 和 IPv6 的 `2001:db8::/32` - - 通配符主机：`*.mydomain.com`，`192.168.100.*` + - 通配符主机：`*.mydomain.com` + - 链路本地和云元数据等保留地址会被拒绝。 - `SKIP_TLS_VERIFY`: **false**: 允许不安全的证书。 - `PAGING_NUM`: **10**: 一页中显示的 Webhook 历史事件数量。 -- `PROXY_URL`: **_empty_**: 代理服务器 URL，支持 http://、https://、socks://，留空将遵循环境的 http_proxy/https_proxy 设置。如果未提供，将使用全局代理设置。 +- `PROXY_URL`: **_empty_**: 代理服务器 URL，支持 http://、https://、socks5://，留空将遵循环境的 http_proxy/https_proxy 设置。如果未提供，将使用全局代理设置。 - `PROXY_HOSTS`: **_empty_**: 需要代理的主机名的逗号分隔列表。支持通配符模式 (\*)；使用 \*\* 来匹配所有主机。如果未提供，将使用全局代理设置。 ## 邮件 (`mailer`) @@ -1277,9 +1276,8 @@ ALLOW_DATA_URI_IMAGES = true - `MAX_ATTEMPTS`：**3**: 每次 http/https 请求的最大尝试次数（用于迁移）。 - `RETRY_BACKOFF`：**3**: 每次 http/https 请求重试的退避时间（秒）。 -- `ALLOWED_DOMAINS`：**_empty_**: 允许迁移仓库的域名允许列表，默认为空。这意味着允许外部网址。多个域名可以用逗号分隔。支持通配符：`github.com, *.github.com`。 -- `BLOCKED_DOMAINS`：**_empty_**: 阻止迁移仓库的域名阻止列表，默认为空。多个域名可以用逗号分隔。当 `ALLOWED_DOMAINS` 不为空时，此选项优先级较高，用于拒绝域名。支持通配符。 -- `ALLOW_LOCALNETWORKS`：**false**: 允许 RFC 1918、RFC 1122、RFC 4632 和 RFC 4291 中定义的私有地址。如果域名被 `ALLOWED_DOMAINS` 允许，此选项将被忽略。 +- `ALLOWED_HOST_LIST`：**_empty_**: 迁移和镜像可以访问的主机，格式与 `[security]` 的 `ALLOWED_HOST_LIST` 相同。私有和回环地址需要内置或 CIDR 条目。取代已弃用的 `ALLOWED_DOMAINS` 和 `ALLOW_LOCALNETWORKS`。 +- `BLOCKED_HOST_LIST`：**_empty_**: 迁移和镜像禁止访问的主机。取代已弃用的 `BLOCKED_DOMAINS`。 - `SKIP_TLS_VERIFY`：**false**: 允许跳过 TLS 验证。 ## 联邦（`federation`） @@ -1509,14 +1507,14 @@ MINIO_BUCKET_LOOKUP_TYPE = auto ## 代理 (`proxy`) - `PROXY_ENABLED`: **false**: 启用代理，如果为 true，所有通过 HTTP 向外部的请求都将受到影响，如果为 false，即使环境设置了 http_proxy/https_proxy 也不会使用 -- `PROXY_URL`: **_empty_**: 代理服务器地址，支持 http://, https//, socks://，为空则不启用代理而使用环境变量中的 http_proxy/https_proxy +- `PROXY_URL`: **_empty_**: 代理服务器地址，支持 http://, https://, socks5://，为空则不启用代理而使用环境变量中的 http_proxy/https_proxy - `PROXY_HOSTS`: **_empty_**: 逗号分隔的多个需要代理的网址，支持 \* 号匹配符号， \*\* 表示匹配所有网站 i.e. ```ini PROXY_ENABLED = true -PROXY_URL = socks://127.0.0.1:1080 +PROXY_URL = socks5://127.0.0.1:1080 PROXY_HOSTS = *.github.com ``` diff --git a/i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/config-cheat-sheet.md b/i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/config-cheat-sheet.md index 88ce6de7..86bb1537 100644 --- a/i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/config-cheat-sheet.md +++ b/i18n/zh-cn/docusaurus-plugin-content-docs/version-28/administration/config-cheat-sheet.md @@ -681,17 +681,16 @@ Gitea 创建以下非唯一队列： - `QUEUE_LENGTH`: **1000**: 钩子任务队列长度。编辑此值时要小心。 - `DELIVER_TIMEOUT`: **5**: 发送 Webhook 的交付超时时间（秒）。 -- `ALLOWED_HOST_LIST`: **external**: 出于安全原因，Webhook 仅能调用允许的主机。以逗号分隔的列表。 +- `ALLOWED_HOST_LIST`: **_empty_**: 出于安全原因，Webhook 仅能调用允许的主机。以逗号分隔的列表。在默认的 `[security]` `EGRESS_MODE = lax` 下仅限制私有地址。 - 内置网络： - `loopback`：IPv4 的 127.0.0.0/8 和 IPv6 的 ::1/128，包括 localhost。 - - `private`：RFC 1918（10.0.0.0/8，172.16.0.0/12，192.168.0.0/16）和 RFC 4193（FC00::/7）。也称为 LAN/Intranet。 - - `external`：一个有效的非私有单播 IP，您可以访问公共互联网上的所有主机。 - - `*`：允许所有主机。 + - `private`：RFC 1918（10.0.0.0/8，172.16.0.0/12，192.168.0.0/16）、RFC 4193（FC00::/7）和 RFC 6598 CGNAT（100.64.0.0/10）。也称为 LAN/Intranet。 - CIDR 列表：IPv4 的 `1.2.3.0/8` 和 IPv6 的 `2001:db8::/32` - - 通配符主机：`*.mydomain.com`，`192.168.100.*` + - 通配符主机：`*.mydomain.com` + - 链路本地和云元数据等保留地址会被拒绝。 - `SKIP_TLS_VERIFY`: **false**: 允许不安全的证书。 - `PAGING_NUM`: **10**: 一页中显示的 Webhook 历史事件数量。 -- `PROXY_URL`: **_empty_**: 代理服务器 URL，支持 http://、https://、socks://，留空将遵循环境的 http_proxy/https_proxy 设置。如果未提供，将使用全局代理设置。 +- `PROXY_URL`: **_empty_**: 代理服务器 URL，支持 http://、https://、socks5://，留空将遵循环境的 http_proxy/https_proxy 设置。如果未提供，将使用全局代理设置。 - `PROXY_HOSTS`: **_empty_**: 需要代理的主机名的逗号分隔列表。支持通配符模式 (\*)；使用 \*\* 来匹配所有主机。如果未提供，将使用全局代理设置。 ## 邮件 (`mailer`) @@ -1277,9 +1276,8 @@ ALLOW_DATA_URI_IMAGES = true - `MAX_ATTEMPTS`：**3**: 每次 http/https 请求的最大尝试次数（用于迁移）。 - `RETRY_BACKOFF`：**3**: 每次 http/https 请求重试的退避时间（秒）。 -- `ALLOWED_DOMAINS`：**_empty_**: 允许迁移仓库的域名允许列表，默认为空。这意味着允许外部网址。多个域名可以用逗号分隔。支持通配符：`github.com, *.github.com`。 -- `BLOCKED_DOMAINS`：**_empty_**: 阻止迁移仓库的域名阻止列表，默认为空。多个域名可以用逗号分隔。当 `ALLOWED_DOMAINS` 不为空时，此选项优先级较高，用于拒绝域名。支持通配符。 -- `ALLOW_LOCALNETWORKS`：**false**: 允许 RFC 1918、RFC 1122、RFC 4632 和 RFC 4291 中定义的私有地址。如果域名被 `ALLOWED_DOMAINS` 允许，此选项将被忽略。 +- `ALLOWED_HOST_LIST`：**_empty_**: 迁移和镜像可以访问的主机，格式与 `[security]` 的 `ALLOWED_HOST_LIST` 相同。私有和回环地址需要内置或 CIDR 条目。取代已弃用的 `ALLOWED_DOMAINS` 和 `ALLOW_LOCALNETWORKS`。 +- `BLOCKED_HOST_LIST`：**_empty_**: 迁移和镜像禁止访问的主机。取代已弃用的 `BLOCKED_DOMAINS`。 - `SKIP_TLS_VERIFY`：**false**: 允许跳过 TLS 验证。 ## 联邦（`federation`） @@ -1509,14 +1507,14 @@ MINIO_BUCKET_LOOKUP_TYPE = auto ## 代理 (`proxy`) - `PROXY_ENABLED`: **false**: 启用代理，如果为 true，所有通过 HTTP 向外部的请求都将受到影响，如果为 false，即使环境设置了 http_proxy/https_proxy 也不会使用 -- `PROXY_URL`: **_empty_**: 代理服务器地址，支持 http://, https//, socks://，为空则不启用代理而使用环境变量中的 http_proxy/https_proxy +- `PROXY_URL`: **_empty_**: 代理服务器地址，支持 http://, https://, socks5://，为空则不启用代理而使用环境变量中的 http_proxy/https_proxy - `PROXY_HOSTS`: **_empty_**: 逗号分隔的多个需要代理的网址，支持 \* 号匹配符号， \*\* 表示匹配所有网站 i.e. ```ini PROXY_ENABLED = true -PROXY_URL = socks://127.0.0.1:1080 +PROXY_URL = socks5://127.0.0.1:1080 PROXY_HOSTS = *.github.com ``` diff --git a/i18n/zh-tw/docusaurus-plugin-content-docs/current/administration/config-cheat-sheet.md b/i18n/zh-tw/docusaurus-plugin-content-docs/current/administration/config-cheat-sheet.md index 0e19f6f6..a497b120 100644 --- a/i18n/zh-tw/docusaurus-plugin-content-docs/current/administration/config-cheat-sheet.md +++ b/i18n/zh-tw/docusaurus-plugin-content-docs/current/administration/config-cheat-sheet.md @@ -686,17 +686,16 @@ Gitea 建立以下非唯一隊列： - `QUEUE_LENGTH`: **1000**: 鉤子任務隊列長度。編輯此值時要小心。 - `DELIVER_TIMEOUT`: **5**: 發送 Webhook 的交付超時時間（秒）。 -- `ALLOWED_HOST_LIST`: **external**: 出於安全原因，Webhook 僅能調用允許的主機。以逗號分隔的列表。 +- `ALLOWED_HOST_LIST`: **_empty_**: 出於安全原因，Webhook 僅能調用允許的主機。以逗號分隔的列表。在預設的 `[security]` `EGRESS_MODE = lax` 下僅限制私有位址。 - 內置網路： - `loopback`：IPv4 的 127.0.0.0/8 和 IPv6 的 ::1/128，包括 localhost。 - - `private`：RFC 1918（10.0.0.0/8，172.16.0.0/12，192.168.0.0/16）和 RFC 4193（FC00::/7）。也稱為 LAN/Intranet。 - - `external`：一個有效的非私有單播 IP，您可以訪問公共互聯網上的所有主機。 - - `*`：允許所有主機。 + - `private`：RFC 1918（10.0.0.0/8，172.16.0.0/12，192.168.0.0/16）、RFC 4193（FC00::/7）和 RFC 6598 CGNAT（100.64.0.0/10）。也稱為 LAN/Intranet。 - CIDR 列表：IPv4 的 `1.2.3.0/8` 和 IPv6 的 `2001:db8::/32` - - 通配符主機：`*.mydomain.com`，`192.168.100.*` + - 通配符主機：`*.mydomain.com` + - 鏈路本地和雲端元資料等保留地址會被拒絕。 - `SKIP_TLS_VERIFY`: **false**: 允許不安全的證書。 - `PAGING_NUM`: **10**: 一頁中顯示的 Webhook 歷史事件數量。 -- `PROXY_URL`: **_empty_**: 代理伺服器 URL，支援 http://、https://、socks://，留空將遵循環境的 http_proxy/https_proxy 設定。如果未提供，將使用全域代理設定。 +- `PROXY_URL`: **_empty_**: 代理伺服器 URL，支援 http://、https://、socks5://，留空將遵循環境的 http_proxy/https_proxy 設定。如果未提供，將使用全域代理設定。 - `PROXY_HOSTS`: **_empty_**: 需要代理的主機名的逗號分隔列表。支援通配符模式 (\*)；使用 \*\* 來匹配所有主機。如果未提供，將使用全域代理設定。 ## 郵件 (`mailer`) @@ -1283,9 +1282,8 @@ ALLOW_DATA_URI_IMAGES = true - `MAX_ATTEMPTS`：**3**: 每次 http/https 請求的最大嘗試次數（用於遷移）。 - `RETRY_BACKOFF`：**3**: 每次 http/https 請求重試的退避時間（秒）。 -- `ALLOWED_DOMAINS`：**_empty_**: 允許遷移儲存庫的域名允許列表，預設為空。這意味著允許外部網址。多個域名可以用逗號分隔。支援通配符：`github.com, *.github.com`。 -- `BLOCKED_DOMAINS`：**_empty_**: 阻止遷移儲存庫的域名阻止列表，預設為空。多個域名可以用逗號分隔。當 `ALLOWED_DOMAINS` 不為空時，此選項優先級較高，用於拒絕域名。支援通配符。 -- `ALLOW_LOCALNETWORKS`：**false**: 允許 RFC 1918、RFC 1122、RFC 4632 和 RFC 4291 中定義的私有地址。如果域名被 `ALLOWED_DOMAINS` 允許，此選項將被忽略。 +- `ALLOWED_HOST_LIST`：**_empty_**: 遷移和鏡像可以訪問的主機，格式與 `[security]` 的 `ALLOWED_HOST_LIST` 相同。私有和回環地址需要內建或 CIDR 條目。取代已棄用的 `ALLOWED_DOMAINS` 和 `ALLOW_LOCALNETWORKS`。 +- `BLOCKED_HOST_LIST`：**_empty_**: 遷移和鏡像禁止訪問的主機。取代已棄用的 `BLOCKED_DOMAINS`。 - `SKIP_TLS_VERIFY`：**false**: 允許跳過 TLS 驗證。 ## 聯邦（`federation`） @@ -1516,14 +1514,14 @@ MINIO_BUCKET_LOOKUP_TYPE = auto ## 代理 (`proxy`) - `PROXY_ENABLED`: **false**: 啟用代理，如果為 true，所有通過 HTTP 向外部的請求都將受到影響，如果為 false，即使環境設定了 http_proxy/https_proxy 也不會使用 -- `PROXY_URL`: **_empty_**: 代理伺服器地址，支援 http://, https//, socks://，為空則不啟用代理而使用環境變量中的 http_proxy/https_proxy +- `PROXY_URL`: **_empty_**: 代理伺服器地址，支援 http://, https://, socks5://，為空則不啟用代理而使用環境變量中的 http_proxy/https_proxy - `PROXY_HOSTS`: **_empty_**: 逗號分隔的多個需要代理的網址，支援 \* 號匹配符號， \*\* 表示匹配所有網站 i.e. ```ini PROXY_ENABLED = true -PROXY_URL = socks://127.0.0.1:1080 +PROXY_URL = socks5://127.0.0.1:1080 PROXY_HOSTS = *.github.com ``` diff --git a/i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/config-cheat-sheet.md b/i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/config-cheat-sheet.md index 0e19f6f6..a497b120 100644 --- a/i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/config-cheat-sheet.md +++ b/i18n/zh-tw/docusaurus-plugin-content-docs/version-28/administration/config-cheat-sheet.md @@ -686,17 +686,16 @@ Gitea 建立以下非唯一隊列： - `QUEUE_LENGTH`: **1000**: 鉤子任務隊列長度。編輯此值時要小心。 - `DELIVER_TIMEOUT`: **5**: 發送 Webhook 的交付超時時間（秒）。 -- `ALLOWED_HOST_LIST`: **external**: 出於安全原因，Webhook 僅能調用允許的主機。以逗號分隔的列表。 +- `ALLOWED_HOST_LIST`: **_empty_**: 出於安全原因，Webhook 僅能調用允許的主機。以逗號分隔的列表。在預設的 `[security]` `EGRESS_MODE = lax` 下僅限制私有位址。 - 內置網路： - `loopback`：IPv4 的 127.0.0.0/8 和 IPv6 的 ::1/128，包括 localhost。 - - `private`：RFC 1918（10.0.0.0/8，172.16.0.0/12，192.168.0.0/16）和 RFC 4193（FC00::/7）。也稱為 LAN/Intranet。 - - `external`：一個有效的非私有單播 IP，您可以訪問公共互聯網上的所有主機。 - - `*`：允許所有主機。 + - `private`：RFC 1918（10.0.0.0/8，172.16.0.0/12，192.168.0.0/16）、RFC 4193（FC00::/7）和 RFC 6598 CGNAT（100.64.0.0/10）。也稱為 LAN/Intranet。 - CIDR 列表：IPv4 的 `1.2.3.0/8` 和 IPv6 的 `2001:db8::/32` - - 通配符主機：`*.mydomain.com`，`192.168.100.*` + - 通配符主機：`*.mydomain.com` + - 鏈路本地和雲端元資料等保留地址會被拒絕。 - `SKIP_TLS_VERIFY`: **false**: 允許不安全的證書。 - `PAGING_NUM`: **10**: 一頁中顯示的 Webhook 歷史事件數量。 -- `PROXY_URL`: **_empty_**: 代理伺服器 URL，支援 http://、https://、socks://，留空將遵循環境的 http_proxy/https_proxy 設定。如果未提供，將使用全域代理設定。 +- `PROXY_URL`: **_empty_**: 代理伺服器 URL，支援 http://、https://、socks5://，留空將遵循環境的 http_proxy/https_proxy 設定。如果未提供，將使用全域代理設定。 - `PROXY_HOSTS`: **_empty_**: 需要代理的主機名的逗號分隔列表。支援通配符模式 (\*)；使用 \*\* 來匹配所有主機。如果未提供，將使用全域代理設定。 ## 郵件 (`mailer`) @@ -1283,9 +1282,8 @@ ALLOW_DATA_URI_IMAGES = true - `MAX_ATTEMPTS`：**3**: 每次 http/https 請求的最大嘗試次數（用於遷移）。 - `RETRY_BACKOFF`：**3**: 每次 http/https 請求重試的退避時間（秒）。 -- `ALLOWED_DOMAINS`：**_empty_**: 允許遷移儲存庫的域名允許列表，預設為空。這意味著允許外部網址。多個域名可以用逗號分隔。支援通配符：`github.com, *.github.com`。 -- `BLOCKED_DOMAINS`：**_empty_**: 阻止遷移儲存庫的域名阻止列表，預設為空。多個域名可以用逗號分隔。當 `ALLOWED_DOMAINS` 不為空時，此選項優先級較高，用於拒絕域名。支援通配符。 -- `ALLOW_LOCALNETWORKS`：**false**: 允許 RFC 1918、RFC 1122、RFC 4632 和 RFC 4291 中定義的私有地址。如果域名被 `ALLOWED_DOMAINS` 允許，此選項將被忽略。 +- `ALLOWED_HOST_LIST`：**_empty_**: 遷移和鏡像可以訪問的主機，格式與 `[security]` 的 `ALLOWED_HOST_LIST` 相同。私有和回環地址需要內建或 CIDR 條目。取代已棄用的 `ALLOWED_DOMAINS` 和 `ALLOW_LOCALNETWORKS`。 +- `BLOCKED_HOST_LIST`：**_empty_**: 遷移和鏡像禁止訪問的主機。取代已棄用的 `BLOCKED_DOMAINS`。 - `SKIP_TLS_VERIFY`：**false**: 允許跳過 TLS 驗證。 ## 聯邦（`federation`） @@ -1516,14 +1514,14 @@ MINIO_BUCKET_LOOKUP_TYPE = auto ## 代理 (`proxy`) - `PROXY_ENABLED`: **false**: 啟用代理，如果為 true，所有通過 HTTP 向外部的請求都將受到影響，如果為 false，即使環境設定了 http_proxy/https_proxy 也不會使用 -- `PROXY_URL`: **_empty_**: 代理伺服器地址，支援 http://, https//, socks://，為空則不啟用代理而使用環境變量中的 http_proxy/https_proxy +- `PROXY_URL`: **_empty_**: 代理伺服器地址，支援 http://, https://, socks5://，為空則不啟用代理而使用環境變量中的 http_proxy/https_proxy - `PROXY_HOSTS`: **_empty_**: 逗號分隔的多個需要代理的網址，支援 \* 號匹配符號， \*\* 表示匹配所有網站 i.e. ```ini PROXY_ENABLED = true -PROXY_URL = socks://127.0.0.1:1080 +PROXY_URL = socks5://127.0.0.1:1080 PROXY_HOSTS = *.github.com ``` diff --git a/versioned_docs/version-28/administration/config-cheat-sheet.md b/versioned_docs/version-28/administration/config-cheat-sheet.md index 5907d8ba..a21a734e 100644 --- a/versioned_docs/version-28/administration/config-cheat-sheet.md +++ b/versioned_docs/version-28/administration/config-cheat-sheet.md @@ -646,14 +646,24 @@ And the following unique queues: - `SUCCESSFUL_TOKENS_CACHE_SIZE`: **20**: Cache successful token hashes. API tokens are stored in the DB as pbkdf2 hashes however, this means that there is a potentially significant hashing load when there are multiple API operations. This cache will store the successfully hashed tokens in a LRU cache as a balance between performance and security. - `DISABLE_QUERY_AUTH_TOKEN`: **false**: Reject API tokens sent in URL query string (Accept Header-based API tokens only). This setting will default to `true` in Gitea 1.23 and be deprecated in Gitea 1.24. - `TWO_FACTOR_AUTH`: **_empty_**: set to enforced to enforce two factor authentication. Only available in Gitea 1.24 and later. -- `ALLOWED_HOST_LIST`: **external**: Webhook and oauth2 clients can only call allowed hosts for security reasons. Comma separated list. +- `EGRESS_MODE`: **lax**: Egress mode toggles between strictness of outgoing requests: + - `lax` requires addresses to be allowed only if they are in private ranges, it allows all public ones + - `strict` requires an explicit allow of all addresses +- `ALLOWED_HOST_LIST`: **_empty_**: Webhook and oauth2 clients can only call allowed hosts for security reasons. Comma separated list, eg: `192.168.1.0/24:3000`, `[2001:db8::/32]:9090`, `*.mydomain.com:[80|443]` - Built-in networks: - `loopback`: 127.0.0.0/8 for IPv4 and ::1/128 for IPv6, localhost is included. - - `private`: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) and RFC 4193 (FC00::/7). Also called LAN/Intranet. - - `external`: A valid non-private unicast IP, you can access all hosts on public internet. - - `*`: All hosts are allowed. - - CIDR list: `1.2.3.0/8` for IPv4 and `2001:db8::/32` for IPv6 - - Wildcard hosts: `*.mydomain.com`, `192.168.100.*` + - `private`: RFC 1918 (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), RFC 4193 (FC00::/7) and RFC 6598 CGNAT (100.64.0.0/10). Also called LAN/Intranet. + - CIDR list: `1.2.3.0/8`, `2001:db8::/32`, and with a port `[2001:db8::/32]:9090` (IPv6 addresses and CIDRs need brackets when a port is given) + - Host matching: `example.com` matches the host and any subdomain, dot-anchored so `notexample.com` never matches. `*.example.com` and `.example.com` match only subdomains, the apex itself is excluded. IDN names must be given as punycode. + - All addresses can have ports specified. Accepted port specs: + - a single port: `192.168.1.0/24:3000` + - a range, both bounds inclusive: `*.mydomain.com:3000-3010` + - a bracketed set of ports and ranges, `|` separated: `*.mydomain.com:[80|443|3000-3010]` + - all ports: `*.mydomain.com:*` + - A portless entry covers all ports in `lax` mode, only 80 and 443 in `strict` mode + - Port specs apply only where the list is consulted: in `lax` mode that is private, loopback and CGNAT targets alone, public targets are allowed on every port whatever the list says. In `strict` mode every target is checked, so ports restrict public hosts too. + - Reserved addresses like link-local and cloud metadata are denied + - This list is enforced on direct connections only. When an HTTP proxy is configured, restricting the proxied target is the proxy server's responsibility. ## Audit (`audit`) @@ -807,9 +817,11 @@ Define allowed algorithms and their minimum key length (use -1 to disable a type - `DELIVER_TIMEOUT`: **5**: Delivery timeout (sec) for shooting webhooks. - `SKIP_TLS_VERIFY`: **false**: Allow insecure certification. - `PAGING_NUM`: **10**: Number of webhook history events that are shown in one page. -- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https//, socks://, blank will follow environment http_proxy/https_proxy. If not given, will use global proxy setting. +- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https://, socks5://, blank will follow environment http_proxy/https_proxy. If not given, will use global proxy setting. - `PROXY_HOSTS`: **_empty_`**: Comma separated list of host names requiring proxy. Glob patterns (*) are accepted; use ** to match all hosts. If not given, will use global proxy setting. +When a proxy is configured, Gitea does not enforce `[security]` `ALLOWED_HOST_LIST` on the proxied target, the proxy server is expected to restrict it. + ## Mailer (`mailer`) :::warning @@ -1427,11 +1439,13 @@ in this mapping or the filetype using heuristics. - `MAX_ATTEMPTS`: **3**: Max attempts per http/https request on migrations. - `RETRY_BACKOFF`: **3**: Backoff time per http/https request retry (seconds) -- `ALLOWED_DOMAINS`: **_empty_**: Domains allowlist for migrating repositories, default is blank. It means external hosts will be allowed. Multiple domains could be separated by commas. Wildcard is supported: `github.com, *.github.com`. -- `BLOCKED_DOMAINS`: **_empty_**: Domains blocklist for migrating repositories, default is blank. Multiple domains could be separated by commas. When `ALLOWED_DOMAINS` is not blank, this option has a higher priority to deny domains. Wildcard is supported. -- `ALLOW_LOCALNETWORKS`: **false**: Allow private addresses defined by RFC 1918, RFC 1122, RFC 4632 and RFC 4291. If a domain is allowed by `ALLOWED_DOMAINS`, this option will be ignored. +- `EGRESS_MODE`: **lax**: Mode toggles between strictness of scanning outgoing requests, same format as `EGRESS_MODE` in [`security`](#security-security). +- `ALLOWED_HOST_LIST`: **_empty_**: Hosts migrations and mirrors may call, same format as `ALLOWED_HOST_LIST` in [`security`](#security-security). Private and loopback addresses need a builtin or CIDR entry. When unset, the deprecated `ALLOWED_DOMAINS` entries apply on every port with `strict` as the default mode, and the deprecated `ALLOW_LOCALNETWORKS` adds `private, loopback`. +- `BLOCKED_HOST_LIST`: **_empty_**: Hosts migrations and mirrors may never call, portless entries cover all ports. - `SKIP_TLS_VERIFY`: **false**: Allow skip tls verify +These lists are enforced on direct connections only. When a proxy is configured (`[proxy]`, `[git.config]` `http.proxy` or the environment), restricting the proxied target is the proxy server's responsibility. + ## Federation (`federation`) - `ENABLED`: **false**: Enable/Disable federation capabilities @@ -1666,14 +1680,16 @@ is `data/repo-archive` and the default of `MINIO_BASE_PATH` is `repo-archive/`. ## Proxy (`proxy`) - `PROXY_ENABLED`: **false**: Enable the proxy if true, all requests to external via HTTP will be affected, if false, no proxy will be used even environment http_proxy/https_proxy -- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https//, socks://, blank will follow environment http_proxy/https_proxy +- `PROXY_URL`: **_empty_**: Proxy server URL, support http://, https://, socks5://, blank will follow environment http_proxy/https_proxy - `PROXY_HOSTS`: **_empty_**: Comma separated list of host names requiring proxy. Glob patterns (*) are accepted; use ** to match all hosts. +When a proxy is configured, Gitea does not enforce the egress lists (`[security]`, `[migrations]`) on the proxied target, the proxy server is expected to restrict it. + i.e. ```ini PROXY_ENABLED = true -PROXY_URL = socks://127.0.0.1:1080 +PROXY_URL = socks5://127.0.0.1:1080 PROXY_HOSTS = *.github.com ```