From 3b8dd1eb4ba8da8beb38b05366589874c31e2e1d Mon Sep 17 00:00:00 2001 From: gatewayJ <835269233@qq.com> Date: Tue, 8 Sep 2026 16:46:20 +0800 Subject: [PATCH] docs: fix security references, defaults, and localized links --- .../de/administration/data/object/object-lock.md | 2 +- content/de/installation/linux/quick-start.md | 2 +- content/de/reference/cli.md | 9 ++++++--- content/de/reference/environment-variables.md | 14 ++++++++------ content/de/security-compliance/encryption/kms.md | 13 ++++++++----- content/de/security-compliance/iam/index.md | 6 +++--- content/de/security-compliance/iam/sts.md | 2 +- .../en/administration/data/object/object-lock.md | 2 +- content/en/installation/linux/quick-start.md | 2 +- content/en/reference/cli.md | 9 ++++++--- content/en/reference/environment-variables.md | 14 ++++++++------ content/en/security-compliance/encryption/kms.md | 13 ++++++++----- content/en/security-compliance/iam/index.md | 6 +++--- content/en/security-compliance/iam/sts.md | 2 +- .../fr/administration/data/object/object-lock.md | 2 +- content/fr/installation/linux/quick-start.md | 2 +- content/fr/reference/cli.md | 9 ++++++--- content/fr/reference/environment-variables.md | 14 ++++++++------ content/fr/security-compliance/encryption/kms.md | 13 ++++++++----- content/fr/security-compliance/iam/index.md | 6 +++--- content/fr/security-compliance/iam/sts.md | 2 +- .../ja/administration/data/object/object-lock.md | 2 +- content/ja/installation/linux/quick-start.md | 2 +- content/ja/reference/cli.md | 9 ++++++--- content/ja/reference/environment-variables.md | 14 ++++++++------ content/ja/security-compliance/encryption/kms.md | 13 ++++++++----- content/ja/security-compliance/iam/index.md | 6 +++--- content/ja/security-compliance/iam/sts.md | 2 +- .../zh/administration/data/object/object-lock.md | 2 +- content/zh/installation/linux/quick-start.md | 2 +- content/zh/reference/cli.md | 9 ++++++--- content/zh/reference/environment-variables.md | 14 ++++++++------ content/zh/security-compliance/encryption/kms.md | 13 ++++++++----- content/zh/security-compliance/iam/index.md | 6 +++--- content/zh/security-compliance/iam/sts.md | 2 +- 35 files changed, 140 insertions(+), 100 deletions(-) diff --git a/content/de/administration/data/object/object-lock.md b/content/de/administration/data/object/object-lock.md index 8e35fbf7..5db3468a 100644 --- a/content/de/administration/data/object/object-lock.md +++ b/content/de/administration/data/object/object-lock.md @@ -7,7 +7,7 @@ RustFS Object Lock applies write-once, read-many protection to individual object ## Overview -Object Lock requires bucket versioning and must be enabled when the bucket is created. Each overwrite creates a new version; retention and Legal Hold protect a specific version rather than the object key as a whole. +Object Lock requires bucket versioning. You can enable it when creating a bucket or use the S3 `PutObjectLockConfiguration` API on an existing bucket whose versioning is enabled. Each overwrite creates a new version; retention and Legal Hold protect a specific version rather than the object key as a whole. | Protection | Behavior | | --- | --- | diff --git a/content/de/installation/linux/quick-start.md b/content/de/installation/linux/quick-start.md index c72007b7..b3afc15e 100644 --- a/content/de/installation/linux/quick-start.md +++ b/content/de/installation/linux/quick-start.md @@ -39,7 +39,7 @@ RUSTFS_ACCESS_KEY= RUSTFS_SECRET_KEY= ; e.g. output of: openssl rand -base64 24 ``` -Use an uppercase alphanumeric access key. Do not use unmodified Base64 output for `RUSTFS_ACCESS_KEY`, because Base64 can contain `/`, which conflicts with the AWS Signature Version 4 credential scope. See [Credential Management](/en/operations/credentials) for details. +Use an uppercase alphanumeric access key. Do not use unmodified Base64 output for `RUSTFS_ACCESS_KEY`, because Base64 can contain `/`, which conflicts with the AWS Signature Version 4 credential scope. See [Credential Management](/operations/credentials) for details. ```bash sudo systemctl restart rustfs diff --git a/content/de/reference/cli.md b/content/de/reference/cli.md index ec5a537c..47fc0a90 100644 --- a/content/de/reference/cli.md +++ b/content/de/reference/cli.md @@ -1,9 +1,9 @@ --- title: "CLI Reference" -description: "Reference for the rustfs command-line interface, including the server, info, and tls subcommands, key flags with environment variable equivalents, and volume path syntax." +description: "Reference for the rustfs subcommands, server flags, environment variable equivalents, and volume path syntax." --- -The `rustfs` binary ships three subcommands. Running `rustfs` with no subcommand starts the server. +The `rustfs` binary ships six subcommands. Running `rustfs` with no subcommand starts the server. ## Subcommands @@ -12,6 +12,9 @@ The `rustfs` binary ships three subcommands. Running `rustfs` with no subcommand | `rustfs server [OPTIONS] ...` | Start the object storage server (default when no subcommand is given). | | `rustfs info [--all] [--json] [system\|runtime\|build\|config\|deps]` | Display system, runtime, build, configuration, or dependency information. | | `rustfs tls inspect --path ` | Inspect a TLS certificate directory layout and parsing status. | +| `rustfs diagnose [OPTIONS] ...` | Analyze log files and report probable failure causes. | +| `rustfs inspect ` | Inspect persisted bucket metadata without a running server. | +| `rustfs connect ` | Configure outbound RustFS Connect integration. | ```bash title="Examples" rustfs server /data/rustfs @@ -56,7 +59,7 @@ Every server flag has an environment variable equivalent; the flag wins when bot | `--kms-local-master-key` | `RUSTFS_KMS_LOCAL_MASTER_KEY` | unset | Master key for local KMS key-file encryption. | | `--kms-vault-address` | `RUSTFS_KMS_VAULT_ADDRESS` | unset | Vault address for the Vault backends. | | `--kms-vault-token` | `RUSTFS_KMS_VAULT_TOKEN` | unset | Vault token for the Vault backends. | -| `--kms-vault-mount-path` | `RUSTFS_KMS_VAULT_MOUNT_PATH` | unset | Vault mount path. | +| `--kms-vault-mount-path` | `RUSTFS_KMS_VAULT_MOUNT_PATH` | unset | Transit mount for `vault-transit` (defaults to `transit`); deprecated and unused for `vault` / `vault-kv2`. | | `--kms-default-key-id` | `RUSTFS_KMS_DEFAULT_KEY_ID` | unset | Default KMS key ID for encryption. | | `--kms-allow-insecure-dev-defaults` | `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS` | `false` | Allow development-only insecure KMS defaults. | | `--buffer-profile` | `RUSTFS_BUFFER_PROFILE` | `GeneralPurpose` | Workload profile for adaptive buffer sizing. | diff --git a/content/de/reference/environment-variables.md b/content/de/reference/environment-variables.md index 5933f780..e2f5a8fc 100644 --- a/content/de/reference/environment-variables.md +++ b/content/de/reference/environment-variables.md @@ -56,12 +56,14 @@ See [CORS Configuration](/administration/cors) for configuration and verificatio | `RUSTFS_MTLS_CLIENT_CERT` | unset | Client certificate presented for internode mTLS connections. | | `RUSTFS_MTLS_CLIENT_KEY` | unset | Client private key for internode mTLS connections. | | `RUSTFS_KMS_ENABLE` | `false` | Enable KMS-backed server-side encryption. | -| `RUSTFS_KMS_BACKEND` | `local` | KMS backend: `local`, `vault` / `vault-kv2` (Vault KV2 + Transit), or `vault-transit`. | +| `RUSTFS_KMS_BACKEND` | `local` | KMS backend: `local`, `vault` / `vault-kv2` (Vault KV2 storage with local data-key wrapping), or `vault-transit`. | | `RUSTFS_KMS_KEY_DIR` | unset | Key directory for the `local` backend. | | `RUSTFS_KMS_LOCAL_MASTER_KEY` | unset | Master key protecting local KMS key files. | | `RUSTFS_KMS_VAULT_ADDRESS` | unset | Vault server address for the Vault backends. | | `RUSTFS_KMS_VAULT_TOKEN` | unset | Vault token for the Vault backends. | -| `RUSTFS_KMS_VAULT_MOUNT_PATH` | unset | Vault mount path for the Vault backends. | +| `RUSTFS_KMS_VAULT_MOUNT_PATH` | `transit` | Transit mount for `vault-transit`; deprecated and unused for `vault` / `vault-kv2`. | +| `RUSTFS_KMS_VAULT_KV_MOUNT` | `secret` | KV v2 mount for the `vault` / `vault-kv2` backend. | +| `RUSTFS_KMS_VAULT_KEY_PREFIX` | `rustfs/kms/keys` | Key record prefix within the KV v2 mount for `vault` / `vault-kv2`. | | `RUSTFS_KMS_DEFAULT_KEY_ID` | unset | Default KMS key ID used for encryption. | | `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS` | `false` | Allow development-only insecure KMS defaults. Never enable in production. | @@ -103,14 +105,14 @@ Metrics collection intervals follow the pattern `RUSTFS_METRICS__INTERVAL | `RUSTFS_SCANNER_MAX_WAIT_SECS` | preset | Overrides the maximum scanner sleep in seconds. | | `RUSTFS_SCANNER_CYCLE` | preset | Overrides the scan cycle interval in seconds (e.g. `3600`). | | `RUSTFS_SCANNER_START_DELAY_SECS` | unset | Startup delay in seconds before the first scan cycle. | -| `RUSTFS_SCANNER_CYCLE_MAX_DURATION_SECS` | `0` | Caps one cycle's runtime in seconds; `0` disables the budget. | +| `RUSTFS_SCANNER_CYCLE_MAX_DURATION_SECS` | `1800` | Caps one cycle's runtime in seconds; `0` disables the budget. | | `RUSTFS_SCANNER_CYCLE_MAX_OBJECTS` | `0` | Caps objects processed per cycle; `0` disables the budget. | | `RUSTFS_SCANNER_CYCLE_MAX_DIRECTORIES` | `0` | Caps directories entered per cycle; `0` disables the budget. | | `RUSTFS_SCANNER_BITROT_CYCLE_SECS` | `2592000` | Periodic deep (bitrot) scan cycle in seconds (30 days). `0`/`true`/`on` makes every cycle deep; `false`/`off` disables deep scans. | | `RUSTFS_SCANNER_IDLE_MODE` | `true` | When `true` the scanner throttles itself; `false` runs at full speed. | -| `RUSTFS_SCANNER_CACHE_SAVE_TIMEOUT_SECS` | `30` | Scanner cache save timeout in seconds (minimum `1`). | -| `RUSTFS_SCANNER_MAX_CONCURRENT_SET_SCANS` | `0` | Caps concurrent erasure-set scan tasks; `0` keeps topology-based concurrency. | -| `RUSTFS_SCANNER_MAX_CONCURRENT_DISK_SCANS` | `0` | Caps concurrent disk bucket walks per set; `0` keeps disk-count-based concurrency. | +| `RUSTFS_SCANNER_CACHE_SAVE_TIMEOUT_SECS` | `14` | Scanner cache save timeout in seconds (minimum `1`). | +| `RUSTFS_SCANNER_MAX_CONCURRENT_SET_SCANS` | `4` | Caps concurrent erasure-set scan tasks; `0` keeps topology-based concurrency. | +| `RUSTFS_SCANNER_MAX_CONCURRENT_DISK_SCANS` | `4` | Caps concurrent disk bucket walks per set; `0` keeps disk-count-based concurrency. | | `RUSTFS_SCANNER_YIELD_EVERY_N_OBJECTS` | `128` | How often scanner object loops yield to the async runtime; `0` disables the extra yield. | | `RUSTFS_SCANNER_ALERT_EXCESS_VERSIONS` | `100` | Object version count that triggers scanner alerts. | | `RUSTFS_SCANNER_ALERT_EXCESS_VERSION_SIZE` | `1099511627776` | Cumulative version bytes (1 TiB) that trigger scanner alerts. | diff --git a/content/de/security-compliance/encryption/kms.md b/content/de/security-compliance/encryption/kms.md index 23b3315f..a1db6568 100644 --- a/content/de/security-compliance/encryption/kms.md +++ b/content/de/security-compliance/encryption/kms.md @@ -3,7 +3,7 @@ title: "SSE-KMS" description: "Configure SSE-KMS with a local or HashiCorp Vault KMS backend for RustFS." --- -RustFS Key Management Service (KMS) generates and wraps per-object data encryption keys for [SSE-S3](./sse-s.md) and SSE-KMS. This guide configures SSE-KMS at server startup with a local key store, Vault KV v2 plus Transit, or Vault Transit. +RustFS Key Management Service (KMS) generates and wraps per-object data encryption keys for [SSE-S3](./sse-s.md) and SSE-KMS. This guide configures SSE-KMS at server startup with a local key store, Vault KV v2, or Vault Transit. ## Requirements @@ -25,7 +25,7 @@ RustFS does not store a recoverable copy of your KMS master key outside the conf | Backend | `RUSTFS_KMS_BACKEND` | Key storage and wrapping | Intended use | | --- | --- | --- | --- | | Local | `local` | Key files on the RustFS host | Development, testing, or a carefully backed-up single-host deployment | -| Vault KV2 | `vault` or `vault-kv2` | Metadata in Vault KV v2; wrapping through Vault Transit | Centralized production key management | +| Vault KV2 | `vault` or `vault-kv2` | Master key material in Vault KV v2; data-key wrapping in RustFS | Centralized key storage | | Vault Transit | `vault-transit` | Cryptographic operations through Vault Transit | Centralized production key management without the KV2 backend mode | SSE-S3 and SSE-KMS both require the KMS service to be running. Configuring a bucket default alone does not make encrypted writes succeed when KMS is unavailable. @@ -58,17 +58,20 @@ sudo systemctl status rustfs --no-pager ## Configure Vault KV2 -Enable a KV v2 engine for key metadata and a Transit engine for key wrapping. Then configure every RustFS node: +Enable a KV v2 engine for master key material and metadata. RustFS reads the master key material and wraps data keys locally; this backend does not call Vault Transit. Configure every RustFS node: ```ini title="/etc/default/rustfs" RUSTFS_KMS_ENABLE=true RUSTFS_KMS_BACKEND=vault-kv2 RUSTFS_KMS_VAULT_ADDRESS=https://vault.example.com:8200 RUSTFS_KMS_VAULT_TOKEN= -RUSTFS_KMS_VAULT_MOUNT_PATH=transit +RUSTFS_KMS_VAULT_KV_MOUNT=secret +RUSTFS_KMS_VAULT_KEY_PREFIX=rustfs/kms/keys ``` -The server startup interface uses `secret` as the KV mount and `rustfs/kms/keys` as the key prefix. Use a Vault token that can read and write that KV path and perform the required Transit operations. +The KV mount defaults to `secret` and the key prefix to `rustfs/kms/keys`; the variables above let you select different paths. Use a Vault token authorized for the configured KV data and metadata paths. `RUSTFS_KMS_VAULT_MOUNT_PATH` is deprecated and unused for the KV2 backend. + +Master key material is Base64-encoded in KV2. Any identity with KV read access to the key path can recover the plaintext master key, so restrict that access to trusted RustFS identities. RustFS validates the Vault URL and rejects insecure development defaults unless `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS=true` is set. Use HTTPS and a certificate trusted by the RustFS hosts in production. diff --git a/content/de/security-compliance/iam/index.md b/content/de/security-compliance/iam/index.md index 53b0ccf3..2d23161d 100644 --- a/content/de/security-compliance/iam/index.md +++ b/content/de/security-compliance/iam/index.md @@ -11,7 +11,7 @@ RustFS distinguishes the following identity types: | Identity | Created by | Typical use | | --- | --- | --- | -| Root credentials | `RUSTFS_ACCESS_KEY` / `RUSTFS_SECRET_KEY` environment variables at server start | Initial setup and break-glass administration. The root account bypasses policy checks (owner semantics). | +| Root credentials | `RUSTFS_ACCESS_KEY` / `RUSTFS_SECRET_KEY` environment variables at server start | Initial setup and break-glass administration. The root account bypasses IAM identity-policy evaluation (owner semantics). | | IAM users | Console or admin API (`add-user`) | Long-term named accounts for people or applications. | | Groups | Console or admin API (`update-group-members`) | Attach one policy set to many users at once. Users inherit the policies of every group they belong to. | | Service accounts (access keys) | Console or admin API (`add-service-account`) | Derived credentials that belong to a parent user. They inherit the parent's permissions, optionally restricted further by an embedded session policy, and can carry an expiration time. | @@ -20,7 +20,7 @@ RustFS distinguishes the following identity types: :::warning -Root credentials cannot be restricted by policies. Use them only to bootstrap the deployment, then create IAM users and service accounts for day-to-day work. +Root credentials bypass IAM identity policies, but bucket policies can still deny root S3 requests. Only `GetBucketPolicy`, `PutBucketPolicy`, and `DeleteBucketPolicy` bypass a bucket-policy deny so the owner can recover access. Use root credentials only to bootstrap the deployment, then create IAM users and service accounts for day-to-day work. ::: @@ -41,7 +41,7 @@ RustFS ships these built-in (canned) policies: `readwrite`, `readonly`, `writeon When an identity has multiple attached policies, RustFS merges their statements (dropping duplicates) and evaluates the merged document: 1. **Explicit deny wins.** All `Deny` statements are checked first; if any matching `Deny` statement applies to the request, the request is rejected regardless of any `Allow`. -2. **Owner shortcut.** The root (owner) account is allowed once no explicit deny matched. +2. **Owner shortcut.** The root account bypasses IAM identity-policy evaluation; the bucket-policy checks and exceptions described above still apply. 3. **Explicit allow required.** Otherwise, at least one `Allow` statement must match the requested action and resource. 4. **Default deny.** If no statement matches, the request is denied. diff --git a/content/de/security-compliance/iam/sts.md b/content/de/security-compliance/iam/sts.md index 8f9d2c09..8ba58d53 100644 --- a/content/de/security-compliance/iam/sts.md +++ b/content/de/security-compliance/iam/sts.md @@ -57,7 +57,7 @@ RustFS implements an AWS-compatible STS endpoint at the server root (`POST /` wi ### AssumeRole -The request must be signed (AWS Signature V4) by a long-term IAM credential — temporary credentials and service accounts cannot call `AssumeRole`. The calling identity also needs the `sts:AssumeRole` action allowed by its policies (all built-in policies include it). +The request must be signed (AWS Signature V4) by a long-term IAM credential — temporary credentials and service accounts cannot call `AssumeRole`. With built-in IAM authorization, RustFS evaluates `sts:AssumeRole` for regular IAM users in deny-only mode: a matching explicit `Deny` rejects the request, but a separate `Allow` is not required. The user must have at least one applicable user or group policy binding, and all bound policy names must resolve. Form parameters: diff --git a/content/en/administration/data/object/object-lock.md b/content/en/administration/data/object/object-lock.md index 8e35fbf7..5db3468a 100644 --- a/content/en/administration/data/object/object-lock.md +++ b/content/en/administration/data/object/object-lock.md @@ -7,7 +7,7 @@ RustFS Object Lock applies write-once, read-many protection to individual object ## Overview -Object Lock requires bucket versioning and must be enabled when the bucket is created. Each overwrite creates a new version; retention and Legal Hold protect a specific version rather than the object key as a whole. +Object Lock requires bucket versioning. You can enable it when creating a bucket or use the S3 `PutObjectLockConfiguration` API on an existing bucket whose versioning is enabled. Each overwrite creates a new version; retention and Legal Hold protect a specific version rather than the object key as a whole. | Protection | Behavior | | --- | --- | diff --git a/content/en/installation/linux/quick-start.md b/content/en/installation/linux/quick-start.md index c72007b7..b3afc15e 100644 --- a/content/en/installation/linux/quick-start.md +++ b/content/en/installation/linux/quick-start.md @@ -39,7 +39,7 @@ RUSTFS_ACCESS_KEY= RUSTFS_SECRET_KEY= ; e.g. output of: openssl rand -base64 24 ``` -Use an uppercase alphanumeric access key. Do not use unmodified Base64 output for `RUSTFS_ACCESS_KEY`, because Base64 can contain `/`, which conflicts with the AWS Signature Version 4 credential scope. See [Credential Management](/en/operations/credentials) for details. +Use an uppercase alphanumeric access key. Do not use unmodified Base64 output for `RUSTFS_ACCESS_KEY`, because Base64 can contain `/`, which conflicts with the AWS Signature Version 4 credential scope. See [Credential Management](/operations/credentials) for details. ```bash sudo systemctl restart rustfs diff --git a/content/en/reference/cli.md b/content/en/reference/cli.md index ec5a537c..47fc0a90 100644 --- a/content/en/reference/cli.md +++ b/content/en/reference/cli.md @@ -1,9 +1,9 @@ --- title: "CLI Reference" -description: "Reference for the rustfs command-line interface, including the server, info, and tls subcommands, key flags with environment variable equivalents, and volume path syntax." +description: "Reference for the rustfs subcommands, server flags, environment variable equivalents, and volume path syntax." --- -The `rustfs` binary ships three subcommands. Running `rustfs` with no subcommand starts the server. +The `rustfs` binary ships six subcommands. Running `rustfs` with no subcommand starts the server. ## Subcommands @@ -12,6 +12,9 @@ The `rustfs` binary ships three subcommands. Running `rustfs` with no subcommand | `rustfs server [OPTIONS] ...` | Start the object storage server (default when no subcommand is given). | | `rustfs info [--all] [--json] [system\|runtime\|build\|config\|deps]` | Display system, runtime, build, configuration, or dependency information. | | `rustfs tls inspect --path ` | Inspect a TLS certificate directory layout and parsing status. | +| `rustfs diagnose [OPTIONS] ...` | Analyze log files and report probable failure causes. | +| `rustfs inspect ` | Inspect persisted bucket metadata without a running server. | +| `rustfs connect ` | Configure outbound RustFS Connect integration. | ```bash title="Examples" rustfs server /data/rustfs @@ -56,7 +59,7 @@ Every server flag has an environment variable equivalent; the flag wins when bot | `--kms-local-master-key` | `RUSTFS_KMS_LOCAL_MASTER_KEY` | unset | Master key for local KMS key-file encryption. | | `--kms-vault-address` | `RUSTFS_KMS_VAULT_ADDRESS` | unset | Vault address for the Vault backends. | | `--kms-vault-token` | `RUSTFS_KMS_VAULT_TOKEN` | unset | Vault token for the Vault backends. | -| `--kms-vault-mount-path` | `RUSTFS_KMS_VAULT_MOUNT_PATH` | unset | Vault mount path. | +| `--kms-vault-mount-path` | `RUSTFS_KMS_VAULT_MOUNT_PATH` | unset | Transit mount for `vault-transit` (defaults to `transit`); deprecated and unused for `vault` / `vault-kv2`. | | `--kms-default-key-id` | `RUSTFS_KMS_DEFAULT_KEY_ID` | unset | Default KMS key ID for encryption. | | `--kms-allow-insecure-dev-defaults` | `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS` | `false` | Allow development-only insecure KMS defaults. | | `--buffer-profile` | `RUSTFS_BUFFER_PROFILE` | `GeneralPurpose` | Workload profile for adaptive buffer sizing. | diff --git a/content/en/reference/environment-variables.md b/content/en/reference/environment-variables.md index 5933f780..e2f5a8fc 100644 --- a/content/en/reference/environment-variables.md +++ b/content/en/reference/environment-variables.md @@ -56,12 +56,14 @@ See [CORS Configuration](/administration/cors) for configuration and verificatio | `RUSTFS_MTLS_CLIENT_CERT` | unset | Client certificate presented for internode mTLS connections. | | `RUSTFS_MTLS_CLIENT_KEY` | unset | Client private key for internode mTLS connections. | | `RUSTFS_KMS_ENABLE` | `false` | Enable KMS-backed server-side encryption. | -| `RUSTFS_KMS_BACKEND` | `local` | KMS backend: `local`, `vault` / `vault-kv2` (Vault KV2 + Transit), or `vault-transit`. | +| `RUSTFS_KMS_BACKEND` | `local` | KMS backend: `local`, `vault` / `vault-kv2` (Vault KV2 storage with local data-key wrapping), or `vault-transit`. | | `RUSTFS_KMS_KEY_DIR` | unset | Key directory for the `local` backend. | | `RUSTFS_KMS_LOCAL_MASTER_KEY` | unset | Master key protecting local KMS key files. | | `RUSTFS_KMS_VAULT_ADDRESS` | unset | Vault server address for the Vault backends. | | `RUSTFS_KMS_VAULT_TOKEN` | unset | Vault token for the Vault backends. | -| `RUSTFS_KMS_VAULT_MOUNT_PATH` | unset | Vault mount path for the Vault backends. | +| `RUSTFS_KMS_VAULT_MOUNT_PATH` | `transit` | Transit mount for `vault-transit`; deprecated and unused for `vault` / `vault-kv2`. | +| `RUSTFS_KMS_VAULT_KV_MOUNT` | `secret` | KV v2 mount for the `vault` / `vault-kv2` backend. | +| `RUSTFS_KMS_VAULT_KEY_PREFIX` | `rustfs/kms/keys` | Key record prefix within the KV v2 mount for `vault` / `vault-kv2`. | | `RUSTFS_KMS_DEFAULT_KEY_ID` | unset | Default KMS key ID used for encryption. | | `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS` | `false` | Allow development-only insecure KMS defaults. Never enable in production. | @@ -103,14 +105,14 @@ Metrics collection intervals follow the pattern `RUSTFS_METRICS__INTERVAL | `RUSTFS_SCANNER_MAX_WAIT_SECS` | preset | Overrides the maximum scanner sleep in seconds. | | `RUSTFS_SCANNER_CYCLE` | preset | Overrides the scan cycle interval in seconds (e.g. `3600`). | | `RUSTFS_SCANNER_START_DELAY_SECS` | unset | Startup delay in seconds before the first scan cycle. | -| `RUSTFS_SCANNER_CYCLE_MAX_DURATION_SECS` | `0` | Caps one cycle's runtime in seconds; `0` disables the budget. | +| `RUSTFS_SCANNER_CYCLE_MAX_DURATION_SECS` | `1800` | Caps one cycle's runtime in seconds; `0` disables the budget. | | `RUSTFS_SCANNER_CYCLE_MAX_OBJECTS` | `0` | Caps objects processed per cycle; `0` disables the budget. | | `RUSTFS_SCANNER_CYCLE_MAX_DIRECTORIES` | `0` | Caps directories entered per cycle; `0` disables the budget. | | `RUSTFS_SCANNER_BITROT_CYCLE_SECS` | `2592000` | Periodic deep (bitrot) scan cycle in seconds (30 days). `0`/`true`/`on` makes every cycle deep; `false`/`off` disables deep scans. | | `RUSTFS_SCANNER_IDLE_MODE` | `true` | When `true` the scanner throttles itself; `false` runs at full speed. | -| `RUSTFS_SCANNER_CACHE_SAVE_TIMEOUT_SECS` | `30` | Scanner cache save timeout in seconds (minimum `1`). | -| `RUSTFS_SCANNER_MAX_CONCURRENT_SET_SCANS` | `0` | Caps concurrent erasure-set scan tasks; `0` keeps topology-based concurrency. | -| `RUSTFS_SCANNER_MAX_CONCURRENT_DISK_SCANS` | `0` | Caps concurrent disk bucket walks per set; `0` keeps disk-count-based concurrency. | +| `RUSTFS_SCANNER_CACHE_SAVE_TIMEOUT_SECS` | `14` | Scanner cache save timeout in seconds (minimum `1`). | +| `RUSTFS_SCANNER_MAX_CONCURRENT_SET_SCANS` | `4` | Caps concurrent erasure-set scan tasks; `0` keeps topology-based concurrency. | +| `RUSTFS_SCANNER_MAX_CONCURRENT_DISK_SCANS` | `4` | Caps concurrent disk bucket walks per set; `0` keeps disk-count-based concurrency. | | `RUSTFS_SCANNER_YIELD_EVERY_N_OBJECTS` | `128` | How often scanner object loops yield to the async runtime; `0` disables the extra yield. | | `RUSTFS_SCANNER_ALERT_EXCESS_VERSIONS` | `100` | Object version count that triggers scanner alerts. | | `RUSTFS_SCANNER_ALERT_EXCESS_VERSION_SIZE` | `1099511627776` | Cumulative version bytes (1 TiB) that trigger scanner alerts. | diff --git a/content/en/security-compliance/encryption/kms.md b/content/en/security-compliance/encryption/kms.md index 23b3315f..a1db6568 100644 --- a/content/en/security-compliance/encryption/kms.md +++ b/content/en/security-compliance/encryption/kms.md @@ -3,7 +3,7 @@ title: "SSE-KMS" description: "Configure SSE-KMS with a local or HashiCorp Vault KMS backend for RustFS." --- -RustFS Key Management Service (KMS) generates and wraps per-object data encryption keys for [SSE-S3](./sse-s.md) and SSE-KMS. This guide configures SSE-KMS at server startup with a local key store, Vault KV v2 plus Transit, or Vault Transit. +RustFS Key Management Service (KMS) generates and wraps per-object data encryption keys for [SSE-S3](./sse-s.md) and SSE-KMS. This guide configures SSE-KMS at server startup with a local key store, Vault KV v2, or Vault Transit. ## Requirements @@ -25,7 +25,7 @@ RustFS does not store a recoverable copy of your KMS master key outside the conf | Backend | `RUSTFS_KMS_BACKEND` | Key storage and wrapping | Intended use | | --- | --- | --- | --- | | Local | `local` | Key files on the RustFS host | Development, testing, or a carefully backed-up single-host deployment | -| Vault KV2 | `vault` or `vault-kv2` | Metadata in Vault KV v2; wrapping through Vault Transit | Centralized production key management | +| Vault KV2 | `vault` or `vault-kv2` | Master key material in Vault KV v2; data-key wrapping in RustFS | Centralized key storage | | Vault Transit | `vault-transit` | Cryptographic operations through Vault Transit | Centralized production key management without the KV2 backend mode | SSE-S3 and SSE-KMS both require the KMS service to be running. Configuring a bucket default alone does not make encrypted writes succeed when KMS is unavailable. @@ -58,17 +58,20 @@ sudo systemctl status rustfs --no-pager ## Configure Vault KV2 -Enable a KV v2 engine for key metadata and a Transit engine for key wrapping. Then configure every RustFS node: +Enable a KV v2 engine for master key material and metadata. RustFS reads the master key material and wraps data keys locally; this backend does not call Vault Transit. Configure every RustFS node: ```ini title="/etc/default/rustfs" RUSTFS_KMS_ENABLE=true RUSTFS_KMS_BACKEND=vault-kv2 RUSTFS_KMS_VAULT_ADDRESS=https://vault.example.com:8200 RUSTFS_KMS_VAULT_TOKEN= -RUSTFS_KMS_VAULT_MOUNT_PATH=transit +RUSTFS_KMS_VAULT_KV_MOUNT=secret +RUSTFS_KMS_VAULT_KEY_PREFIX=rustfs/kms/keys ``` -The server startup interface uses `secret` as the KV mount and `rustfs/kms/keys` as the key prefix. Use a Vault token that can read and write that KV path and perform the required Transit operations. +The KV mount defaults to `secret` and the key prefix to `rustfs/kms/keys`; the variables above let you select different paths. Use a Vault token authorized for the configured KV data and metadata paths. `RUSTFS_KMS_VAULT_MOUNT_PATH` is deprecated and unused for the KV2 backend. + +Master key material is Base64-encoded in KV2. Any identity with KV read access to the key path can recover the plaintext master key, so restrict that access to trusted RustFS identities. RustFS validates the Vault URL and rejects insecure development defaults unless `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS=true` is set. Use HTTPS and a certificate trusted by the RustFS hosts in production. diff --git a/content/en/security-compliance/iam/index.md b/content/en/security-compliance/iam/index.md index 53b0ccf3..2d23161d 100644 --- a/content/en/security-compliance/iam/index.md +++ b/content/en/security-compliance/iam/index.md @@ -11,7 +11,7 @@ RustFS distinguishes the following identity types: | Identity | Created by | Typical use | | --- | --- | --- | -| Root credentials | `RUSTFS_ACCESS_KEY` / `RUSTFS_SECRET_KEY` environment variables at server start | Initial setup and break-glass administration. The root account bypasses policy checks (owner semantics). | +| Root credentials | `RUSTFS_ACCESS_KEY` / `RUSTFS_SECRET_KEY` environment variables at server start | Initial setup and break-glass administration. The root account bypasses IAM identity-policy evaluation (owner semantics). | | IAM users | Console or admin API (`add-user`) | Long-term named accounts for people or applications. | | Groups | Console or admin API (`update-group-members`) | Attach one policy set to many users at once. Users inherit the policies of every group they belong to. | | Service accounts (access keys) | Console or admin API (`add-service-account`) | Derived credentials that belong to a parent user. They inherit the parent's permissions, optionally restricted further by an embedded session policy, and can carry an expiration time. | @@ -20,7 +20,7 @@ RustFS distinguishes the following identity types: :::warning -Root credentials cannot be restricted by policies. Use them only to bootstrap the deployment, then create IAM users and service accounts for day-to-day work. +Root credentials bypass IAM identity policies, but bucket policies can still deny root S3 requests. Only `GetBucketPolicy`, `PutBucketPolicy`, and `DeleteBucketPolicy` bypass a bucket-policy deny so the owner can recover access. Use root credentials only to bootstrap the deployment, then create IAM users and service accounts for day-to-day work. ::: @@ -41,7 +41,7 @@ RustFS ships these built-in (canned) policies: `readwrite`, `readonly`, `writeon When an identity has multiple attached policies, RustFS merges their statements (dropping duplicates) and evaluates the merged document: 1. **Explicit deny wins.** All `Deny` statements are checked first; if any matching `Deny` statement applies to the request, the request is rejected regardless of any `Allow`. -2. **Owner shortcut.** The root (owner) account is allowed once no explicit deny matched. +2. **Owner shortcut.** The root account bypasses IAM identity-policy evaluation; the bucket-policy checks and exceptions described above still apply. 3. **Explicit allow required.** Otherwise, at least one `Allow` statement must match the requested action and resource. 4. **Default deny.** If no statement matches, the request is denied. diff --git a/content/en/security-compliance/iam/sts.md b/content/en/security-compliance/iam/sts.md index 8f9d2c09..8ba58d53 100644 --- a/content/en/security-compliance/iam/sts.md +++ b/content/en/security-compliance/iam/sts.md @@ -57,7 +57,7 @@ RustFS implements an AWS-compatible STS endpoint at the server root (`POST /` wi ### AssumeRole -The request must be signed (AWS Signature V4) by a long-term IAM credential — temporary credentials and service accounts cannot call `AssumeRole`. The calling identity also needs the `sts:AssumeRole` action allowed by its policies (all built-in policies include it). +The request must be signed (AWS Signature V4) by a long-term IAM credential — temporary credentials and service accounts cannot call `AssumeRole`. With built-in IAM authorization, RustFS evaluates `sts:AssumeRole` for regular IAM users in deny-only mode: a matching explicit `Deny` rejects the request, but a separate `Allow` is not required. The user must have at least one applicable user or group policy binding, and all bound policy names must resolve. Form parameters: diff --git a/content/fr/administration/data/object/object-lock.md b/content/fr/administration/data/object/object-lock.md index 8e35fbf7..5db3468a 100644 --- a/content/fr/administration/data/object/object-lock.md +++ b/content/fr/administration/data/object/object-lock.md @@ -7,7 +7,7 @@ RustFS Object Lock applies write-once, read-many protection to individual object ## Overview -Object Lock requires bucket versioning and must be enabled when the bucket is created. Each overwrite creates a new version; retention and Legal Hold protect a specific version rather than the object key as a whole. +Object Lock requires bucket versioning. You can enable it when creating a bucket or use the S3 `PutObjectLockConfiguration` API on an existing bucket whose versioning is enabled. Each overwrite creates a new version; retention and Legal Hold protect a specific version rather than the object key as a whole. | Protection | Behavior | | --- | --- | diff --git a/content/fr/installation/linux/quick-start.md b/content/fr/installation/linux/quick-start.md index c72007b7..b3afc15e 100644 --- a/content/fr/installation/linux/quick-start.md +++ b/content/fr/installation/linux/quick-start.md @@ -39,7 +39,7 @@ RUSTFS_ACCESS_KEY= RUSTFS_SECRET_KEY= ; e.g. output of: openssl rand -base64 24 ``` -Use an uppercase alphanumeric access key. Do not use unmodified Base64 output for `RUSTFS_ACCESS_KEY`, because Base64 can contain `/`, which conflicts with the AWS Signature Version 4 credential scope. See [Credential Management](/en/operations/credentials) for details. +Use an uppercase alphanumeric access key. Do not use unmodified Base64 output for `RUSTFS_ACCESS_KEY`, because Base64 can contain `/`, which conflicts with the AWS Signature Version 4 credential scope. See [Credential Management](/operations/credentials) for details. ```bash sudo systemctl restart rustfs diff --git a/content/fr/reference/cli.md b/content/fr/reference/cli.md index ec5a537c..47fc0a90 100644 --- a/content/fr/reference/cli.md +++ b/content/fr/reference/cli.md @@ -1,9 +1,9 @@ --- title: "CLI Reference" -description: "Reference for the rustfs command-line interface, including the server, info, and tls subcommands, key flags with environment variable equivalents, and volume path syntax." +description: "Reference for the rustfs subcommands, server flags, environment variable equivalents, and volume path syntax." --- -The `rustfs` binary ships three subcommands. Running `rustfs` with no subcommand starts the server. +The `rustfs` binary ships six subcommands. Running `rustfs` with no subcommand starts the server. ## Subcommands @@ -12,6 +12,9 @@ The `rustfs` binary ships three subcommands. Running `rustfs` with no subcommand | `rustfs server [OPTIONS] ...` | Start the object storage server (default when no subcommand is given). | | `rustfs info [--all] [--json] [system\|runtime\|build\|config\|deps]` | Display system, runtime, build, configuration, or dependency information. | | `rustfs tls inspect --path ` | Inspect a TLS certificate directory layout and parsing status. | +| `rustfs diagnose [OPTIONS] ...` | Analyze log files and report probable failure causes. | +| `rustfs inspect ` | Inspect persisted bucket metadata without a running server. | +| `rustfs connect ` | Configure outbound RustFS Connect integration. | ```bash title="Examples" rustfs server /data/rustfs @@ -56,7 +59,7 @@ Every server flag has an environment variable equivalent; the flag wins when bot | `--kms-local-master-key` | `RUSTFS_KMS_LOCAL_MASTER_KEY` | unset | Master key for local KMS key-file encryption. | | `--kms-vault-address` | `RUSTFS_KMS_VAULT_ADDRESS` | unset | Vault address for the Vault backends. | | `--kms-vault-token` | `RUSTFS_KMS_VAULT_TOKEN` | unset | Vault token for the Vault backends. | -| `--kms-vault-mount-path` | `RUSTFS_KMS_VAULT_MOUNT_PATH` | unset | Vault mount path. | +| `--kms-vault-mount-path` | `RUSTFS_KMS_VAULT_MOUNT_PATH` | unset | Transit mount for `vault-transit` (defaults to `transit`); deprecated and unused for `vault` / `vault-kv2`. | | `--kms-default-key-id` | `RUSTFS_KMS_DEFAULT_KEY_ID` | unset | Default KMS key ID for encryption. | | `--kms-allow-insecure-dev-defaults` | `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS` | `false` | Allow development-only insecure KMS defaults. | | `--buffer-profile` | `RUSTFS_BUFFER_PROFILE` | `GeneralPurpose` | Workload profile for adaptive buffer sizing. | diff --git a/content/fr/reference/environment-variables.md b/content/fr/reference/environment-variables.md index 5933f780..e2f5a8fc 100644 --- a/content/fr/reference/environment-variables.md +++ b/content/fr/reference/environment-variables.md @@ -56,12 +56,14 @@ See [CORS Configuration](/administration/cors) for configuration and verificatio | `RUSTFS_MTLS_CLIENT_CERT` | unset | Client certificate presented for internode mTLS connections. | | `RUSTFS_MTLS_CLIENT_KEY` | unset | Client private key for internode mTLS connections. | | `RUSTFS_KMS_ENABLE` | `false` | Enable KMS-backed server-side encryption. | -| `RUSTFS_KMS_BACKEND` | `local` | KMS backend: `local`, `vault` / `vault-kv2` (Vault KV2 + Transit), or `vault-transit`. | +| `RUSTFS_KMS_BACKEND` | `local` | KMS backend: `local`, `vault` / `vault-kv2` (Vault KV2 storage with local data-key wrapping), or `vault-transit`. | | `RUSTFS_KMS_KEY_DIR` | unset | Key directory for the `local` backend. | | `RUSTFS_KMS_LOCAL_MASTER_KEY` | unset | Master key protecting local KMS key files. | | `RUSTFS_KMS_VAULT_ADDRESS` | unset | Vault server address for the Vault backends. | | `RUSTFS_KMS_VAULT_TOKEN` | unset | Vault token for the Vault backends. | -| `RUSTFS_KMS_VAULT_MOUNT_PATH` | unset | Vault mount path for the Vault backends. | +| `RUSTFS_KMS_VAULT_MOUNT_PATH` | `transit` | Transit mount for `vault-transit`; deprecated and unused for `vault` / `vault-kv2`. | +| `RUSTFS_KMS_VAULT_KV_MOUNT` | `secret` | KV v2 mount for the `vault` / `vault-kv2` backend. | +| `RUSTFS_KMS_VAULT_KEY_PREFIX` | `rustfs/kms/keys` | Key record prefix within the KV v2 mount for `vault` / `vault-kv2`. | | `RUSTFS_KMS_DEFAULT_KEY_ID` | unset | Default KMS key ID used for encryption. | | `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS` | `false` | Allow development-only insecure KMS defaults. Never enable in production. | @@ -103,14 +105,14 @@ Metrics collection intervals follow the pattern `RUSTFS_METRICS__INTERVAL | `RUSTFS_SCANNER_MAX_WAIT_SECS` | preset | Overrides the maximum scanner sleep in seconds. | | `RUSTFS_SCANNER_CYCLE` | preset | Overrides the scan cycle interval in seconds (e.g. `3600`). | | `RUSTFS_SCANNER_START_DELAY_SECS` | unset | Startup delay in seconds before the first scan cycle. | -| `RUSTFS_SCANNER_CYCLE_MAX_DURATION_SECS` | `0` | Caps one cycle's runtime in seconds; `0` disables the budget. | +| `RUSTFS_SCANNER_CYCLE_MAX_DURATION_SECS` | `1800` | Caps one cycle's runtime in seconds; `0` disables the budget. | | `RUSTFS_SCANNER_CYCLE_MAX_OBJECTS` | `0` | Caps objects processed per cycle; `0` disables the budget. | | `RUSTFS_SCANNER_CYCLE_MAX_DIRECTORIES` | `0` | Caps directories entered per cycle; `0` disables the budget. | | `RUSTFS_SCANNER_BITROT_CYCLE_SECS` | `2592000` | Periodic deep (bitrot) scan cycle in seconds (30 days). `0`/`true`/`on` makes every cycle deep; `false`/`off` disables deep scans. | | `RUSTFS_SCANNER_IDLE_MODE` | `true` | When `true` the scanner throttles itself; `false` runs at full speed. | -| `RUSTFS_SCANNER_CACHE_SAVE_TIMEOUT_SECS` | `30` | Scanner cache save timeout in seconds (minimum `1`). | -| `RUSTFS_SCANNER_MAX_CONCURRENT_SET_SCANS` | `0` | Caps concurrent erasure-set scan tasks; `0` keeps topology-based concurrency. | -| `RUSTFS_SCANNER_MAX_CONCURRENT_DISK_SCANS` | `0` | Caps concurrent disk bucket walks per set; `0` keeps disk-count-based concurrency. | +| `RUSTFS_SCANNER_CACHE_SAVE_TIMEOUT_SECS` | `14` | Scanner cache save timeout in seconds (minimum `1`). | +| `RUSTFS_SCANNER_MAX_CONCURRENT_SET_SCANS` | `4` | Caps concurrent erasure-set scan tasks; `0` keeps topology-based concurrency. | +| `RUSTFS_SCANNER_MAX_CONCURRENT_DISK_SCANS` | `4` | Caps concurrent disk bucket walks per set; `0` keeps disk-count-based concurrency. | | `RUSTFS_SCANNER_YIELD_EVERY_N_OBJECTS` | `128` | How often scanner object loops yield to the async runtime; `0` disables the extra yield. | | `RUSTFS_SCANNER_ALERT_EXCESS_VERSIONS` | `100` | Object version count that triggers scanner alerts. | | `RUSTFS_SCANNER_ALERT_EXCESS_VERSION_SIZE` | `1099511627776` | Cumulative version bytes (1 TiB) that trigger scanner alerts. | diff --git a/content/fr/security-compliance/encryption/kms.md b/content/fr/security-compliance/encryption/kms.md index 23b3315f..a1db6568 100644 --- a/content/fr/security-compliance/encryption/kms.md +++ b/content/fr/security-compliance/encryption/kms.md @@ -3,7 +3,7 @@ title: "SSE-KMS" description: "Configure SSE-KMS with a local or HashiCorp Vault KMS backend for RustFS." --- -RustFS Key Management Service (KMS) generates and wraps per-object data encryption keys for [SSE-S3](./sse-s.md) and SSE-KMS. This guide configures SSE-KMS at server startup with a local key store, Vault KV v2 plus Transit, or Vault Transit. +RustFS Key Management Service (KMS) generates and wraps per-object data encryption keys for [SSE-S3](./sse-s.md) and SSE-KMS. This guide configures SSE-KMS at server startup with a local key store, Vault KV v2, or Vault Transit. ## Requirements @@ -25,7 +25,7 @@ RustFS does not store a recoverable copy of your KMS master key outside the conf | Backend | `RUSTFS_KMS_BACKEND` | Key storage and wrapping | Intended use | | --- | --- | --- | --- | | Local | `local` | Key files on the RustFS host | Development, testing, or a carefully backed-up single-host deployment | -| Vault KV2 | `vault` or `vault-kv2` | Metadata in Vault KV v2; wrapping through Vault Transit | Centralized production key management | +| Vault KV2 | `vault` or `vault-kv2` | Master key material in Vault KV v2; data-key wrapping in RustFS | Centralized key storage | | Vault Transit | `vault-transit` | Cryptographic operations through Vault Transit | Centralized production key management without the KV2 backend mode | SSE-S3 and SSE-KMS both require the KMS service to be running. Configuring a bucket default alone does not make encrypted writes succeed when KMS is unavailable. @@ -58,17 +58,20 @@ sudo systemctl status rustfs --no-pager ## Configure Vault KV2 -Enable a KV v2 engine for key metadata and a Transit engine for key wrapping. Then configure every RustFS node: +Enable a KV v2 engine for master key material and metadata. RustFS reads the master key material and wraps data keys locally; this backend does not call Vault Transit. Configure every RustFS node: ```ini title="/etc/default/rustfs" RUSTFS_KMS_ENABLE=true RUSTFS_KMS_BACKEND=vault-kv2 RUSTFS_KMS_VAULT_ADDRESS=https://vault.example.com:8200 RUSTFS_KMS_VAULT_TOKEN= -RUSTFS_KMS_VAULT_MOUNT_PATH=transit +RUSTFS_KMS_VAULT_KV_MOUNT=secret +RUSTFS_KMS_VAULT_KEY_PREFIX=rustfs/kms/keys ``` -The server startup interface uses `secret` as the KV mount and `rustfs/kms/keys` as the key prefix. Use a Vault token that can read and write that KV path and perform the required Transit operations. +The KV mount defaults to `secret` and the key prefix to `rustfs/kms/keys`; the variables above let you select different paths. Use a Vault token authorized for the configured KV data and metadata paths. `RUSTFS_KMS_VAULT_MOUNT_PATH` is deprecated and unused for the KV2 backend. + +Master key material is Base64-encoded in KV2. Any identity with KV read access to the key path can recover the plaintext master key, so restrict that access to trusted RustFS identities. RustFS validates the Vault URL and rejects insecure development defaults unless `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS=true` is set. Use HTTPS and a certificate trusted by the RustFS hosts in production. diff --git a/content/fr/security-compliance/iam/index.md b/content/fr/security-compliance/iam/index.md index 53b0ccf3..2d23161d 100644 --- a/content/fr/security-compliance/iam/index.md +++ b/content/fr/security-compliance/iam/index.md @@ -11,7 +11,7 @@ RustFS distinguishes the following identity types: | Identity | Created by | Typical use | | --- | --- | --- | -| Root credentials | `RUSTFS_ACCESS_KEY` / `RUSTFS_SECRET_KEY` environment variables at server start | Initial setup and break-glass administration. The root account bypasses policy checks (owner semantics). | +| Root credentials | `RUSTFS_ACCESS_KEY` / `RUSTFS_SECRET_KEY` environment variables at server start | Initial setup and break-glass administration. The root account bypasses IAM identity-policy evaluation (owner semantics). | | IAM users | Console or admin API (`add-user`) | Long-term named accounts for people or applications. | | Groups | Console or admin API (`update-group-members`) | Attach one policy set to many users at once. Users inherit the policies of every group they belong to. | | Service accounts (access keys) | Console or admin API (`add-service-account`) | Derived credentials that belong to a parent user. They inherit the parent's permissions, optionally restricted further by an embedded session policy, and can carry an expiration time. | @@ -20,7 +20,7 @@ RustFS distinguishes the following identity types: :::warning -Root credentials cannot be restricted by policies. Use them only to bootstrap the deployment, then create IAM users and service accounts for day-to-day work. +Root credentials bypass IAM identity policies, but bucket policies can still deny root S3 requests. Only `GetBucketPolicy`, `PutBucketPolicy`, and `DeleteBucketPolicy` bypass a bucket-policy deny so the owner can recover access. Use root credentials only to bootstrap the deployment, then create IAM users and service accounts for day-to-day work. ::: @@ -41,7 +41,7 @@ RustFS ships these built-in (canned) policies: `readwrite`, `readonly`, `writeon When an identity has multiple attached policies, RustFS merges their statements (dropping duplicates) and evaluates the merged document: 1. **Explicit deny wins.** All `Deny` statements are checked first; if any matching `Deny` statement applies to the request, the request is rejected regardless of any `Allow`. -2. **Owner shortcut.** The root (owner) account is allowed once no explicit deny matched. +2. **Owner shortcut.** The root account bypasses IAM identity-policy evaluation; the bucket-policy checks and exceptions described above still apply. 3. **Explicit allow required.** Otherwise, at least one `Allow` statement must match the requested action and resource. 4. **Default deny.** If no statement matches, the request is denied. diff --git a/content/fr/security-compliance/iam/sts.md b/content/fr/security-compliance/iam/sts.md index 8f9d2c09..8ba58d53 100644 --- a/content/fr/security-compliance/iam/sts.md +++ b/content/fr/security-compliance/iam/sts.md @@ -57,7 +57,7 @@ RustFS implements an AWS-compatible STS endpoint at the server root (`POST /` wi ### AssumeRole -The request must be signed (AWS Signature V4) by a long-term IAM credential — temporary credentials and service accounts cannot call `AssumeRole`. The calling identity also needs the `sts:AssumeRole` action allowed by its policies (all built-in policies include it). +The request must be signed (AWS Signature V4) by a long-term IAM credential — temporary credentials and service accounts cannot call `AssumeRole`. With built-in IAM authorization, RustFS evaluates `sts:AssumeRole` for regular IAM users in deny-only mode: a matching explicit `Deny` rejects the request, but a separate `Allow` is not required. The user must have at least one applicable user or group policy binding, and all bound policy names must resolve. Form parameters: diff --git a/content/ja/administration/data/object/object-lock.md b/content/ja/administration/data/object/object-lock.md index 8e35fbf7..5db3468a 100644 --- a/content/ja/administration/data/object/object-lock.md +++ b/content/ja/administration/data/object/object-lock.md @@ -7,7 +7,7 @@ RustFS Object Lock applies write-once, read-many protection to individual object ## Overview -Object Lock requires bucket versioning and must be enabled when the bucket is created. Each overwrite creates a new version; retention and Legal Hold protect a specific version rather than the object key as a whole. +Object Lock requires bucket versioning. You can enable it when creating a bucket or use the S3 `PutObjectLockConfiguration` API on an existing bucket whose versioning is enabled. Each overwrite creates a new version; retention and Legal Hold protect a specific version rather than the object key as a whole. | Protection | Behavior | | --- | --- | diff --git a/content/ja/installation/linux/quick-start.md b/content/ja/installation/linux/quick-start.md index c72007b7..b3afc15e 100644 --- a/content/ja/installation/linux/quick-start.md +++ b/content/ja/installation/linux/quick-start.md @@ -39,7 +39,7 @@ RUSTFS_ACCESS_KEY= RUSTFS_SECRET_KEY= ; e.g. output of: openssl rand -base64 24 ``` -Use an uppercase alphanumeric access key. Do not use unmodified Base64 output for `RUSTFS_ACCESS_KEY`, because Base64 can contain `/`, which conflicts with the AWS Signature Version 4 credential scope. See [Credential Management](/en/operations/credentials) for details. +Use an uppercase alphanumeric access key. Do not use unmodified Base64 output for `RUSTFS_ACCESS_KEY`, because Base64 can contain `/`, which conflicts with the AWS Signature Version 4 credential scope. See [Credential Management](/operations/credentials) for details. ```bash sudo systemctl restart rustfs diff --git a/content/ja/reference/cli.md b/content/ja/reference/cli.md index ec5a537c..47fc0a90 100644 --- a/content/ja/reference/cli.md +++ b/content/ja/reference/cli.md @@ -1,9 +1,9 @@ --- title: "CLI Reference" -description: "Reference for the rustfs command-line interface, including the server, info, and tls subcommands, key flags with environment variable equivalents, and volume path syntax." +description: "Reference for the rustfs subcommands, server flags, environment variable equivalents, and volume path syntax." --- -The `rustfs` binary ships three subcommands. Running `rustfs` with no subcommand starts the server. +The `rustfs` binary ships six subcommands. Running `rustfs` with no subcommand starts the server. ## Subcommands @@ -12,6 +12,9 @@ The `rustfs` binary ships three subcommands. Running `rustfs` with no subcommand | `rustfs server [OPTIONS] ...` | Start the object storage server (default when no subcommand is given). | | `rustfs info [--all] [--json] [system\|runtime\|build\|config\|deps]` | Display system, runtime, build, configuration, or dependency information. | | `rustfs tls inspect --path ` | Inspect a TLS certificate directory layout and parsing status. | +| `rustfs diagnose [OPTIONS] ...` | Analyze log files and report probable failure causes. | +| `rustfs inspect ` | Inspect persisted bucket metadata without a running server. | +| `rustfs connect ` | Configure outbound RustFS Connect integration. | ```bash title="Examples" rustfs server /data/rustfs @@ -56,7 +59,7 @@ Every server flag has an environment variable equivalent; the flag wins when bot | `--kms-local-master-key` | `RUSTFS_KMS_LOCAL_MASTER_KEY` | unset | Master key for local KMS key-file encryption. | | `--kms-vault-address` | `RUSTFS_KMS_VAULT_ADDRESS` | unset | Vault address for the Vault backends. | | `--kms-vault-token` | `RUSTFS_KMS_VAULT_TOKEN` | unset | Vault token for the Vault backends. | -| `--kms-vault-mount-path` | `RUSTFS_KMS_VAULT_MOUNT_PATH` | unset | Vault mount path. | +| `--kms-vault-mount-path` | `RUSTFS_KMS_VAULT_MOUNT_PATH` | unset | Transit mount for `vault-transit` (defaults to `transit`); deprecated and unused for `vault` / `vault-kv2`. | | `--kms-default-key-id` | `RUSTFS_KMS_DEFAULT_KEY_ID` | unset | Default KMS key ID for encryption. | | `--kms-allow-insecure-dev-defaults` | `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS` | `false` | Allow development-only insecure KMS defaults. | | `--buffer-profile` | `RUSTFS_BUFFER_PROFILE` | `GeneralPurpose` | Workload profile for adaptive buffer sizing. | diff --git a/content/ja/reference/environment-variables.md b/content/ja/reference/environment-variables.md index 5933f780..e2f5a8fc 100644 --- a/content/ja/reference/environment-variables.md +++ b/content/ja/reference/environment-variables.md @@ -56,12 +56,14 @@ See [CORS Configuration](/administration/cors) for configuration and verificatio | `RUSTFS_MTLS_CLIENT_CERT` | unset | Client certificate presented for internode mTLS connections. | | `RUSTFS_MTLS_CLIENT_KEY` | unset | Client private key for internode mTLS connections. | | `RUSTFS_KMS_ENABLE` | `false` | Enable KMS-backed server-side encryption. | -| `RUSTFS_KMS_BACKEND` | `local` | KMS backend: `local`, `vault` / `vault-kv2` (Vault KV2 + Transit), or `vault-transit`. | +| `RUSTFS_KMS_BACKEND` | `local` | KMS backend: `local`, `vault` / `vault-kv2` (Vault KV2 storage with local data-key wrapping), or `vault-transit`. | | `RUSTFS_KMS_KEY_DIR` | unset | Key directory for the `local` backend. | | `RUSTFS_KMS_LOCAL_MASTER_KEY` | unset | Master key protecting local KMS key files. | | `RUSTFS_KMS_VAULT_ADDRESS` | unset | Vault server address for the Vault backends. | | `RUSTFS_KMS_VAULT_TOKEN` | unset | Vault token for the Vault backends. | -| `RUSTFS_KMS_VAULT_MOUNT_PATH` | unset | Vault mount path for the Vault backends. | +| `RUSTFS_KMS_VAULT_MOUNT_PATH` | `transit` | Transit mount for `vault-transit`; deprecated and unused for `vault` / `vault-kv2`. | +| `RUSTFS_KMS_VAULT_KV_MOUNT` | `secret` | KV v2 mount for the `vault` / `vault-kv2` backend. | +| `RUSTFS_KMS_VAULT_KEY_PREFIX` | `rustfs/kms/keys` | Key record prefix within the KV v2 mount for `vault` / `vault-kv2`. | | `RUSTFS_KMS_DEFAULT_KEY_ID` | unset | Default KMS key ID used for encryption. | | `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS` | `false` | Allow development-only insecure KMS defaults. Never enable in production. | @@ -103,14 +105,14 @@ Metrics collection intervals follow the pattern `RUSTFS_METRICS__INTERVAL | `RUSTFS_SCANNER_MAX_WAIT_SECS` | preset | Overrides the maximum scanner sleep in seconds. | | `RUSTFS_SCANNER_CYCLE` | preset | Overrides the scan cycle interval in seconds (e.g. `3600`). | | `RUSTFS_SCANNER_START_DELAY_SECS` | unset | Startup delay in seconds before the first scan cycle. | -| `RUSTFS_SCANNER_CYCLE_MAX_DURATION_SECS` | `0` | Caps one cycle's runtime in seconds; `0` disables the budget. | +| `RUSTFS_SCANNER_CYCLE_MAX_DURATION_SECS` | `1800` | Caps one cycle's runtime in seconds; `0` disables the budget. | | `RUSTFS_SCANNER_CYCLE_MAX_OBJECTS` | `0` | Caps objects processed per cycle; `0` disables the budget. | | `RUSTFS_SCANNER_CYCLE_MAX_DIRECTORIES` | `0` | Caps directories entered per cycle; `0` disables the budget. | | `RUSTFS_SCANNER_BITROT_CYCLE_SECS` | `2592000` | Periodic deep (bitrot) scan cycle in seconds (30 days). `0`/`true`/`on` makes every cycle deep; `false`/`off` disables deep scans. | | `RUSTFS_SCANNER_IDLE_MODE` | `true` | When `true` the scanner throttles itself; `false` runs at full speed. | -| `RUSTFS_SCANNER_CACHE_SAVE_TIMEOUT_SECS` | `30` | Scanner cache save timeout in seconds (minimum `1`). | -| `RUSTFS_SCANNER_MAX_CONCURRENT_SET_SCANS` | `0` | Caps concurrent erasure-set scan tasks; `0` keeps topology-based concurrency. | -| `RUSTFS_SCANNER_MAX_CONCURRENT_DISK_SCANS` | `0` | Caps concurrent disk bucket walks per set; `0` keeps disk-count-based concurrency. | +| `RUSTFS_SCANNER_CACHE_SAVE_TIMEOUT_SECS` | `14` | Scanner cache save timeout in seconds (minimum `1`). | +| `RUSTFS_SCANNER_MAX_CONCURRENT_SET_SCANS` | `4` | Caps concurrent erasure-set scan tasks; `0` keeps topology-based concurrency. | +| `RUSTFS_SCANNER_MAX_CONCURRENT_DISK_SCANS` | `4` | Caps concurrent disk bucket walks per set; `0` keeps disk-count-based concurrency. | | `RUSTFS_SCANNER_YIELD_EVERY_N_OBJECTS` | `128` | How often scanner object loops yield to the async runtime; `0` disables the extra yield. | | `RUSTFS_SCANNER_ALERT_EXCESS_VERSIONS` | `100` | Object version count that triggers scanner alerts. | | `RUSTFS_SCANNER_ALERT_EXCESS_VERSION_SIZE` | `1099511627776` | Cumulative version bytes (1 TiB) that trigger scanner alerts. | diff --git a/content/ja/security-compliance/encryption/kms.md b/content/ja/security-compliance/encryption/kms.md index 23b3315f..a1db6568 100644 --- a/content/ja/security-compliance/encryption/kms.md +++ b/content/ja/security-compliance/encryption/kms.md @@ -3,7 +3,7 @@ title: "SSE-KMS" description: "Configure SSE-KMS with a local or HashiCorp Vault KMS backend for RustFS." --- -RustFS Key Management Service (KMS) generates and wraps per-object data encryption keys for [SSE-S3](./sse-s.md) and SSE-KMS. This guide configures SSE-KMS at server startup with a local key store, Vault KV v2 plus Transit, or Vault Transit. +RustFS Key Management Service (KMS) generates and wraps per-object data encryption keys for [SSE-S3](./sse-s.md) and SSE-KMS. This guide configures SSE-KMS at server startup with a local key store, Vault KV v2, or Vault Transit. ## Requirements @@ -25,7 +25,7 @@ RustFS does not store a recoverable copy of your KMS master key outside the conf | Backend | `RUSTFS_KMS_BACKEND` | Key storage and wrapping | Intended use | | --- | --- | --- | --- | | Local | `local` | Key files on the RustFS host | Development, testing, or a carefully backed-up single-host deployment | -| Vault KV2 | `vault` or `vault-kv2` | Metadata in Vault KV v2; wrapping through Vault Transit | Centralized production key management | +| Vault KV2 | `vault` or `vault-kv2` | Master key material in Vault KV v2; data-key wrapping in RustFS | Centralized key storage | | Vault Transit | `vault-transit` | Cryptographic operations through Vault Transit | Centralized production key management without the KV2 backend mode | SSE-S3 and SSE-KMS both require the KMS service to be running. Configuring a bucket default alone does not make encrypted writes succeed when KMS is unavailable. @@ -58,17 +58,20 @@ sudo systemctl status rustfs --no-pager ## Configure Vault KV2 -Enable a KV v2 engine for key metadata and a Transit engine for key wrapping. Then configure every RustFS node: +Enable a KV v2 engine for master key material and metadata. RustFS reads the master key material and wraps data keys locally; this backend does not call Vault Transit. Configure every RustFS node: ```ini title="/etc/default/rustfs" RUSTFS_KMS_ENABLE=true RUSTFS_KMS_BACKEND=vault-kv2 RUSTFS_KMS_VAULT_ADDRESS=https://vault.example.com:8200 RUSTFS_KMS_VAULT_TOKEN= -RUSTFS_KMS_VAULT_MOUNT_PATH=transit +RUSTFS_KMS_VAULT_KV_MOUNT=secret +RUSTFS_KMS_VAULT_KEY_PREFIX=rustfs/kms/keys ``` -The server startup interface uses `secret` as the KV mount and `rustfs/kms/keys` as the key prefix. Use a Vault token that can read and write that KV path and perform the required Transit operations. +The KV mount defaults to `secret` and the key prefix to `rustfs/kms/keys`; the variables above let you select different paths. Use a Vault token authorized for the configured KV data and metadata paths. `RUSTFS_KMS_VAULT_MOUNT_PATH` is deprecated and unused for the KV2 backend. + +Master key material is Base64-encoded in KV2. Any identity with KV read access to the key path can recover the plaintext master key, so restrict that access to trusted RustFS identities. RustFS validates the Vault URL and rejects insecure development defaults unless `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS=true` is set. Use HTTPS and a certificate trusted by the RustFS hosts in production. diff --git a/content/ja/security-compliance/iam/index.md b/content/ja/security-compliance/iam/index.md index 53b0ccf3..2d23161d 100644 --- a/content/ja/security-compliance/iam/index.md +++ b/content/ja/security-compliance/iam/index.md @@ -11,7 +11,7 @@ RustFS distinguishes the following identity types: | Identity | Created by | Typical use | | --- | --- | --- | -| Root credentials | `RUSTFS_ACCESS_KEY` / `RUSTFS_SECRET_KEY` environment variables at server start | Initial setup and break-glass administration. The root account bypasses policy checks (owner semantics). | +| Root credentials | `RUSTFS_ACCESS_KEY` / `RUSTFS_SECRET_KEY` environment variables at server start | Initial setup and break-glass administration. The root account bypasses IAM identity-policy evaluation (owner semantics). | | IAM users | Console or admin API (`add-user`) | Long-term named accounts for people or applications. | | Groups | Console or admin API (`update-group-members`) | Attach one policy set to many users at once. Users inherit the policies of every group they belong to. | | Service accounts (access keys) | Console or admin API (`add-service-account`) | Derived credentials that belong to a parent user. They inherit the parent's permissions, optionally restricted further by an embedded session policy, and can carry an expiration time. | @@ -20,7 +20,7 @@ RustFS distinguishes the following identity types: :::warning -Root credentials cannot be restricted by policies. Use them only to bootstrap the deployment, then create IAM users and service accounts for day-to-day work. +Root credentials bypass IAM identity policies, but bucket policies can still deny root S3 requests. Only `GetBucketPolicy`, `PutBucketPolicy`, and `DeleteBucketPolicy` bypass a bucket-policy deny so the owner can recover access. Use root credentials only to bootstrap the deployment, then create IAM users and service accounts for day-to-day work. ::: @@ -41,7 +41,7 @@ RustFS ships these built-in (canned) policies: `readwrite`, `readonly`, `writeon When an identity has multiple attached policies, RustFS merges their statements (dropping duplicates) and evaluates the merged document: 1. **Explicit deny wins.** All `Deny` statements are checked first; if any matching `Deny` statement applies to the request, the request is rejected regardless of any `Allow`. -2. **Owner shortcut.** The root (owner) account is allowed once no explicit deny matched. +2. **Owner shortcut.** The root account bypasses IAM identity-policy evaluation; the bucket-policy checks and exceptions described above still apply. 3. **Explicit allow required.** Otherwise, at least one `Allow` statement must match the requested action and resource. 4. **Default deny.** If no statement matches, the request is denied. diff --git a/content/ja/security-compliance/iam/sts.md b/content/ja/security-compliance/iam/sts.md index 8f9d2c09..8ba58d53 100644 --- a/content/ja/security-compliance/iam/sts.md +++ b/content/ja/security-compliance/iam/sts.md @@ -57,7 +57,7 @@ RustFS implements an AWS-compatible STS endpoint at the server root (`POST /` wi ### AssumeRole -The request must be signed (AWS Signature V4) by a long-term IAM credential — temporary credentials and service accounts cannot call `AssumeRole`. The calling identity also needs the `sts:AssumeRole` action allowed by its policies (all built-in policies include it). +The request must be signed (AWS Signature V4) by a long-term IAM credential — temporary credentials and service accounts cannot call `AssumeRole`. With built-in IAM authorization, RustFS evaluates `sts:AssumeRole` for regular IAM users in deny-only mode: a matching explicit `Deny` rejects the request, but a separate `Allow` is not required. The user must have at least one applicable user or group policy binding, and all bound policy names must resolve. Form parameters: diff --git a/content/zh/administration/data/object/object-lock.md b/content/zh/administration/data/object/object-lock.md index 216c5846..8718acb7 100644 --- a/content/zh/administration/data/object/object-lock.md +++ b/content/zh/administration/data/object/object-lock.md @@ -7,7 +7,7 @@ RustFS 对象锁定为单个对象版本提供一次写入、多次读取保护 ## 概述 -对象锁定要求启用存储桶版本控制，并且必须在创建存储桶时启用。每次覆盖都会创建新版本；保留期和依法保留保护的是特定版本，而不是整个对象键。 +对象锁定要求启用存储桶版本控制。可以在创建存储桶时开启，也可以对已启用版本控制的现有存储桶调用 S3 `PutObjectLockConfiguration` API 开启。每次覆盖都会创建新版本；保留期和依法保留保护的是特定版本，而不是整个对象键。 | 保护方式 | 行为 | | --- | --- | diff --git a/content/zh/installation/linux/quick-start.md b/content/zh/installation/linux/quick-start.md index f4103ad6..0713754e 100644 --- a/content/zh/installation/linux/quick-start.md +++ b/content/zh/installation/linux/quick-start.md @@ -39,7 +39,7 @@ RUSTFS_ACCESS_KEY= RUSTFS_SECRET_KEY= ; e.g. output of: openssl rand -base64 24 ``` -访问密钥请仅使用大写字母和数字。请勿直接将未经转换的 Base64 输出用于 `RUSTFS_ACCESS_KEY`，因为 Base64 可能包含 `/`，与 AWS Signature Version 4 的凭证作用域分隔符冲突。详情请参阅[凭证管理](/zh/operations/credentials)。 +访问密钥请仅使用大写字母和数字。请勿直接将未经转换的 Base64 输出用于 `RUSTFS_ACCESS_KEY`，因为 Base64 可能包含 `/`，与 AWS Signature Version 4 的凭证作用域分隔符冲突。详情请参阅[凭证管理](/operations/credentials)。 ```bash sudo systemctl restart rustfs diff --git a/content/zh/reference/cli.md b/content/zh/reference/cli.md index 3c4ce064..c96f23a5 100644 --- a/content/zh/reference/cli.md +++ b/content/zh/reference/cli.md @@ -1,9 +1,9 @@ --- title: "CLI 参考" -description: "介绍 rustfs 命令行界面，包括 server、info 和 tls 子命令、主要参数及对应环境变量，以及卷路径语法。" +description: "介绍 rustfs 子命令、服务器参数及对应环境变量，以及卷路径语法。" --- -`rustfs` 二进制文件提供三个子命令。不带子命令运行 `rustfs` 时会启动服务器。 +`rustfs` 二进制文件提供六个子命令。不带子命令运行 `rustfs` 时会启动服务器。 ## 子命令 @@ -12,6 +12,9 @@ description: "介绍 rustfs 命令行界面，包括 server、info 和 tls 子 | `rustfs server [OPTIONS] ...` | 启动对象存储服务器（未指定子命令时的默认行为）。 | | `rustfs info [--all] [--json] [system\|runtime\|build\|config\|deps]` | 显示系统、运行时、构建、配置或依赖项信息。 | | `rustfs tls inspect --path ` | 检查 TLS 证书目录布局和解析状态。 | +| `rustfs diagnose [OPTIONS] ...` | 分析日志文件并报告可能的故障原因。 | +| `rustfs inspect ` | 在服务器未运行时检查持久化的存储桶元数据。 | +| `rustfs connect ` | 配置出站 RustFS Connect 集成。 | ```bash title="Examples" rustfs server /data/rustfs @@ -56,7 +59,7 @@ RustFS 会预处理参数以保持向后兼容，因此旧版调用方式仍可 | `--kms-local-master-key` | `RUSTFS_KMS_LOCAL_MASTER_KEY` | 未设置 | 用于加密本地 KMS 密钥文件的主密钥。 | | `--kms-vault-address` | `RUSTFS_KMS_VAULT_ADDRESS` | 未设置 | Vault 后端的 Vault 地址。 | | `--kms-vault-token` | `RUSTFS_KMS_VAULT_TOKEN` | 未设置 | Vault 后端的 Vault 令牌。 | -| `--kms-vault-mount-path` | `RUSTFS_KMS_VAULT_MOUNT_PATH` | 未设置 | Vault 挂载路径。 | +| `--kms-vault-mount-path` | `RUSTFS_KMS_VAULT_MOUNT_PATH` | 未设置 | `vault-transit` 的 Transit 挂载点（默认为 `transit`）；对 `vault` / `vault-kv2` 已弃用且不生效。 | | `--kms-default-key-id` | `RUSTFS_KMS_DEFAULT_KEY_ID` | 未设置 | 用于加密的默认 KMS 密钥 ID。 | | `--kms-allow-insecure-dev-defaults` | `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS` | `false` | 允许仅用于开发的不安全 KMS 默认值。 | | `--buffer-profile` | `RUSTFS_BUFFER_PROFILE` | `GeneralPurpose` | 自适应缓冲区大小的工作负载配置。 | diff --git a/content/zh/reference/environment-variables.md b/content/zh/reference/environment-variables.md index ff9eac1c..70ddd5c5 100644 --- a/content/zh/reference/environment-variables.md +++ b/content/zh/reference/environment-variables.md @@ -56,12 +56,14 @@ description: "介绍用于配置 RustFS 服务器、控制台、TLS、KMS、可 | `RUSTFS_MTLS_CLIENT_CERT` | 未设置 | 节点间 mTLS 连接提供的客户端证书。 | | `RUSTFS_MTLS_CLIENT_KEY` | 未设置 | 节点间 mTLS 连接使用的客户端私钥。 | | `RUSTFS_KMS_ENABLE` | `false` | 启用由 KMS 支持的服务端加密。 | -| `RUSTFS_KMS_BACKEND` | `local` | KMS 后端：`local`、`vault` / `vault-kv2`（Vault KV2 + Transit）或 `vault-transit`。 | +| `RUSTFS_KMS_BACKEND` | `local` | KMS 后端：`local`、`vault` / `vault-kv2`（Vault KV2 存储，在本地封装数据密钥）或 `vault-transit`。 | | `RUSTFS_KMS_KEY_DIR` | 未设置 | `local` 后端的密钥目录。 | | `RUSTFS_KMS_LOCAL_MASTER_KEY` | 未设置 | 保护本地 KMS 密钥文件的主密钥。 | | `RUSTFS_KMS_VAULT_ADDRESS` | 未设置 | Vault 后端的 Vault 服务器地址。 | | `RUSTFS_KMS_VAULT_TOKEN` | 未设置 | Vault 后端的 Vault 令牌。 | -| `RUSTFS_KMS_VAULT_MOUNT_PATH` | 未设置 | Vault 后端的 Vault 挂载路径。 | +| `RUSTFS_KMS_VAULT_MOUNT_PATH` | `transit` | `vault-transit` 的 Transit 挂载点；对 `vault` / `vault-kv2` 已弃用且不生效。 | +| `RUSTFS_KMS_VAULT_KV_MOUNT` | `secret` | `vault` / `vault-kv2` 后端的 KV v2 挂载点。 | +| `RUSTFS_KMS_VAULT_KEY_PREFIX` | `rustfs/kms/keys` | `vault` / `vault-kv2` 后端在 KV v2 挂载点中的密钥记录前缀。 | | `RUSTFS_KMS_DEFAULT_KEY_ID` | 未设置 | 用于加密的默认 KMS 密钥 ID。 | | `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS` | `false` | 允许仅用于开发的不安全 KMS 默认值。切勿在生产环境中启用。 | @@ -103,14 +105,14 @@ description: "介绍用于配置 RustFS 服务器、控制台、TLS、KMS、可 | `RUSTFS_SCANNER_MAX_WAIT_SECS` | 预设值 | 覆盖扫描器最长休眠秒数。 | | `RUSTFS_SCANNER_CYCLE` | 预设值 | 覆盖扫描周期的秒数（例如 `3600`）。 | | `RUSTFS_SCANNER_START_DELAY_SECS` | 未设置 | 第一个扫描周期开始前的启动延迟秒数。 | -| `RUSTFS_SCANNER_CYCLE_MAX_DURATION_SECS` | `0` | 限制单个周期的运行秒数；`0` 表示禁用该预算。 | +| `RUSTFS_SCANNER_CYCLE_MAX_DURATION_SECS` | `1800` | 限制单个周期的运行秒数；`0` 表示禁用该预算。 | | `RUSTFS_SCANNER_CYCLE_MAX_OBJECTS` | `0` | 限制每个周期处理的对象数；`0` 表示禁用该预算。 | | `RUSTFS_SCANNER_CYCLE_MAX_DIRECTORIES` | `0` | 限制每个周期进入的目录数；`0` 表示禁用该预算。 | | `RUSTFS_SCANNER_BITROT_CYCLE_SECS` | `2592000` | 定期深度（位衰减）扫描周期的秒数（30 天）。`0`/`true`/`on` 使每个周期都执行深度扫描；`false`/`off` 禁用深度扫描。 | | `RUSTFS_SCANNER_IDLE_MODE` | `true` | 为 `true` 时扫描器会自行限速；为 `false` 时全速运行。 | -| `RUSTFS_SCANNER_CACHE_SAVE_TIMEOUT_SECS` | `30` | 扫描器缓存保存超时秒数（最小值为 `1`）。 | -| `RUSTFS_SCANNER_MAX_CONCURRENT_SET_SCANS` | `0` | 限制并发纠删集扫描任务数；`0` 保留基于拓扑的并发数。 | -| `RUSTFS_SCANNER_MAX_CONCURRENT_DISK_SCANS` | `0` | 限制每个纠删集并发执行的磁盘存储桶遍历数；`0` 保留基于磁盘数量的并发数。 | +| `RUSTFS_SCANNER_CACHE_SAVE_TIMEOUT_SECS` | `14` | 扫描器缓存保存超时秒数（最小值为 `1`）。 | +| `RUSTFS_SCANNER_MAX_CONCURRENT_SET_SCANS` | `4` | 限制并发纠删集扫描任务数；`0` 保留基于拓扑的并发数。 | +| `RUSTFS_SCANNER_MAX_CONCURRENT_DISK_SCANS` | `4` | 限制每个纠删集并发执行的磁盘存储桶遍历数；`0` 保留基于磁盘数量的并发数。 | | `RUSTFS_SCANNER_YIELD_EVERY_N_OBJECTS` | `128` | 扫描器对象循环向异步运行时让出的频率；`0` 禁用额外让出。 | | `RUSTFS_SCANNER_ALERT_EXCESS_VERSIONS` | `100` | 触发扫描器告警的对象版本数。 | | `RUSTFS_SCANNER_ALERT_EXCESS_VERSION_SIZE` | `1099511627776` | 触发扫描器告警的累计版本字节数（1 TiB）。 | diff --git a/content/zh/security-compliance/encryption/kms.md b/content/zh/security-compliance/encryption/kms.md index e63f6714..863de971 100644 --- a/content/zh/security-compliance/encryption/kms.md +++ b/content/zh/security-compliance/encryption/kms.md @@ -3,7 +3,7 @@ title: "SSE-KMS" description: "使用本地或 HashiCorp Vault KMS 后端为 RustFS 配置 SSE-KMS。" --- -RustFS 密钥管理服务（KMS）为 [SSE-S3](./sse-s.md) 和 SSE-KMS 生成并封装每对象数据加密密钥。本指南介绍如何在服务器启动时使用本地密钥存储、Vault KV v2 加 Transit 或 Vault Transit 配置 SSE-KMS。 +RustFS 密钥管理服务（KMS）为 [SSE-S3](./sse-s.md) 和 SSE-KMS 生成并封装每对象数据加密密钥。本指南介绍如何在服务器启动时使用本地密钥存储、Vault KV v2 或 Vault Transit 配置 SSE-KMS。 ## 要求 @@ -25,7 +25,7 @@ RustFS 不会在配置的后端之外存储可恢复的 KMS 主密钥副本。 | 后端 | `RUSTFS_KMS_BACKEND` | 密钥存储和封装 | 适用场景 | | --- | --- | --- | --- | | Local | `local` | RustFS 主机上的密钥文件 | 开发、测试或经过审慎备份的单主机部署 | -| Vault KV2 | `vault` 或 `vault-kv2` | 元数据存储在 Vault KV v2 中；通过 Vault Transit 进行封装 | 集中式生产密钥管理 | +| Vault KV2 | `vault` 或 `vault-kv2` | 主密钥材料存储在 Vault KV v2 中；由 RustFS 封装数据密钥 | 集中式密钥存储 | | Vault Transit | `vault-transit` | 通过 Vault Transit 执行加密操作 | 不使用 KV2 后端模式的集中式生产密钥管理 | SSE-S3 和 SSE-KMS 都要求 KMS 服务正在运行。当 KMS 不可用时，仅配置存储桶默认设置并不能使加密写入成功。 @@ -58,17 +58,20 @@ sudo systemctl status rustfs --no-pager ## 配置 Vault KV2 -为密钥元数据启用 KV v2 引擎，并为密钥封装启用 Transit 引擎。然后配置每个 RustFS 节点： +为主密钥材料和元数据启用 KV v2 引擎。RustFS 读取主密钥材料并在本地封装数据密钥；此后端不调用 Vault Transit。配置每个 RustFS 节点： ```ini title="/etc/default/rustfs" RUSTFS_KMS_ENABLE=true RUSTFS_KMS_BACKEND=vault-kv2 RUSTFS_KMS_VAULT_ADDRESS=https://vault.example.com:8200 RUSTFS_KMS_VAULT_TOKEN= -RUSTFS_KMS_VAULT_MOUNT_PATH=transit +RUSTFS_KMS_VAULT_KV_MOUNT=secret +RUSTFS_KMS_VAULT_KEY_PREFIX=rustfs/kms/keys ``` -服务器启动接口使用 `secret` 作为 KV 挂载点，使用 `rustfs/kms/keys` 作为密钥前缀。使用能够读写该 KV 路径并执行所需 Transit 操作的 Vault 令牌。 +KV 挂载点默认为 `secret`，密钥前缀默认为 `rustfs/kms/keys`；可通过上述变量选择其他路径。使用有权访问所配置 KV 数据路径和元数据路径的 Vault 令牌。`RUSTFS_KMS_VAULT_MOUNT_PATH` 对 KV2 后端已弃用且不生效。 + +主密钥材料在 KV2 中以 Base64 编码保存。任何对密钥路径具有 KV 读取权限的身份都能恢复明文主密钥，因此应将该权限限制在受信任的 RustFS 身份范围内。 RustFS 会验证 Vault URL；除非设置 `RUSTFS_KMS_ALLOW_INSECURE_DEV_DEFAULTS=true`，否则会拒绝不安全的开发默认值。在生产环境中使用 HTTPS 以及 RustFS 主机信任的证书。 diff --git a/content/zh/security-compliance/iam/index.md b/content/zh/security-compliance/iam/index.md index 91295404..392ad383 100644 --- a/content/zh/security-compliance/iam/index.md +++ b/content/zh/security-compliance/iam/index.md @@ -11,7 +11,7 @@ RustFS 区分以下身份类型： | 身份 | 创建方式 | 典型用途 | | --- | --- | --- | -| 根凭证 | 服务器启动时通过 `RUSTFS_ACCESS_KEY` / `RUSTFS_SECRET_KEY` 环境变量创建 | 初始设置和紧急管理。根账户绕过策略检查（所有者语义）。 | +| 根凭证 | 服务器启动时通过 `RUSTFS_ACCESS_KEY` / `RUSTFS_SECRET_KEY` 环境变量创建 | 初始设置和紧急管理。根账户绕过 IAM 身份策略评估（所有者语义）。 | | IAM 用户 | 控制台或管理 API（`add-user`） | 面向人员或应用程序的长期命名账户。 | | 组 | 控制台或管理 API（`update-group-members`） | 一次将一组策略附加到多个用户。用户会继承其所属每个组的策略。 | | 服务账户（访问密钥） | 控制台或管理 API（`add-service-account`） | 属于父用户的派生凭证。它们继承父用户的权限，可选择通过嵌入式会话策略进一步限制权限，还可以设置过期时间。 | @@ -20,7 +20,7 @@ RustFS 区分以下身份类型： :::warning -策略无法限制根凭证。请仅使用根凭证引导部署，然后创建 IAM 用户和服务账户来处理日常工作。 +根凭证绕过 IAM 身份策略，但存储桶策略仍可拒绝根账户的 S3 请求。只有 `GetBucketPolicy`、`PutBucketPolicy` 和 `DeleteBucketPolicy` 可以绕过存储桶策略的拒绝，以便所有者恢复访问。请仅使用根凭证引导部署，然后创建 IAM 用户和服务账户来处理日常工作。 ::: @@ -41,7 +41,7 @@ RustFS 附带以下内置（预定义）策略：`readwrite`、`readonly`、`wri 当一个身份附加了多个策略时，RustFS 会合并这些策略的语句（删除重复项），并评估合并后的文档： 1. **显式拒绝优先。** 首先检查所有 `Deny` 语句；如果任何匹配的 `Deny` 语句适用于请求，无论是否存在 `Allow`，都会拒绝该请求。 -2. **所有者快捷规则。** 如果没有匹配到显式拒绝，则允许根（所有者）账户的请求。 +2. **所有者快捷规则。** 根账户绕过 IAM 身份策略评估；上述存储桶策略检查及其例外仍然适用。 3. **必须显式允许。** 对其他身份，必须至少有一条 `Allow` 语句与请求的操作和资源匹配。 4. **默认拒绝。** 如果没有语句匹配，则拒绝请求。 diff --git a/content/zh/security-compliance/iam/sts.md b/content/zh/security-compliance/iam/sts.md index e7142dcc..5cfe10c2 100644 --- a/content/zh/security-compliance/iam/sts.md +++ b/content/zh/security-compliance/iam/sts.md @@ -57,7 +57,7 @@ RustFS 在服务器根路径实现了与 AWS 兼容的 STS 端点（使用表单 ### AssumeRole -请求必须由长期 IAM 凭证签名（AWS Signature V4），临时凭证和服务账户不能调用 `AssumeRole`。调用身份还需要其策略允许 `sts:AssumeRole` 操作（所有内置策略均包含此操作）。 +请求必须由长期 IAM 凭证签名（AWS Signature V4），临时凭证和服务账户不能调用 `AssumeRole`。使用内置 IAM 授权时，RustFS 对普通 IAM 用户的 `sts:AssumeRole` 请求采用仅检查拒绝（deny-only）的模式：匹配的显式 `Deny` 会拒绝请求，但不要求单独的 `Allow`。用户必须至少具有一个适用的用户或组策略绑定，且所有绑定的策略名称都必须能解析到对应策略。 表单参数：