update

S3-API-FAQ.md

@@ -252,6 +252,6 @@ key = "/path/to/client.key"
 ca = "/path/to/ca.crt"
 ```
 
-The `[https.filer]` makes the Filer accept HTTPS, while `[https.client]` with `enabled = true` makes clients (S3 API, mount, etc.) use HTTPS for data operations. See [[Security-Configuration]] for details.
+The `[https.filer]` makes the Filer accept HTTPS, while `[https.client]` with `enabled = true` makes clients (S3 API, mount, etc.) use HTTPS for data operations. See [[Security-Overview]] for architecture details and [[Security-Configuration]] for configuration reference.
 
 

Security-Configuration.md

@@ -1,33 +1,6 @@
 
 
-# Understanding Communication Layers
-
-SeaweedFS has two separate communication layers:
-
-## gRPC Communication (Control Plane)
-Used for metadata operations and cluster coordination:
-- S3 ↔ Filer: Getting bucket info, file metadata
-- Filer ↔ Master: Getting volume assignments, cluster info
-- Volume ↔ Master: Heartbeats, volume management
-- **Configured via**: `[grpc.*]` sections in security.toml
-
-## HTTP/HTTPS Communication (Data Plane)
-Used for actual file data uploads/downloads:
-- S3/Filer/Client → Volume Server: Uploading and downloading actual file content
-- **Configured via**: `[https.*]` sections in security.toml
-
-## Configuration Sections Summary
-
-| Configuration Block | Purpose |
-|---------------------|---------|
-| `[grpc.client]`, `[grpc.filer]`, `[grpc.master]`, `[grpc.volume]` | Secure gRPC communication for metadata/control plane |
-| `[https.client]` | Client-side configuration - tells S3/Filer/etc to use HTTPS when communicating with servers |
-| `[https.volume]` | Server-side configuration - makes Volume server accept HTTPS for data uploads |
-| `[https.master]`, `[https.filer]` | Server-side configuration - makes Master/Filer accept HTTPS (web UI, HTTP APIs) |
-
-**Important**: If you enable `[https.filer]` for the Filer server, you must also set `[https.client]` with `enabled = true` so that S3 API uses HTTPS when communicating with the Filer. Otherwise, you'll get "client sent an HTTP request to an HTTPS server" errors.
-
-# Configuration
+For an overview of SeaweedFS security architecture and communication layers, see [[Security-Overview]].
 
 The first step is generating `security.toml` file via `weed scaffold -config=security`:
 
@@ -92,29 +65,38 @@ expires_after_seconds = 10           # seconds
 key = ""
 expires_after_seconds = 10           # seconds
 
-# all grpc tls authentications are mutual
-# the values for the following ca, cert, and key are paths to the PERM files.
-# the host name is not checked, so the PERM files can be shared.
+# gRPC mTLS configuration
+# All gRPC TLS authentications are mutual (mTLS)
+# The values for ca, cert, and key are paths to the certificate/key files
+# The host name is not checked, so the certificate files can be shared
 [grpc]
 ca = ""
 # Set wildcard domain for enable TLS authentication by common names
 allowed_wildcard_domain = "" # .mycompany.com
 
+# Volume server gRPC options (server-side)
+# Enables mTLS for incoming gRPC connections to volume server
 [grpc.volume]
 cert = ""
 key = ""
 allowed_commonNames = ""    # comma-separated SSL certificate common names
 
+# Master server gRPC options (server-side)
+# Enables mTLS for incoming gRPC connections to master server
 [grpc.master]
 cert = ""
 key = ""
 allowed_commonNames = ""    # comma-separated SSL certificate common names
 
+# Filer server gRPC options (server-side)
+# Enables mTLS for incoming gRPC connections to filer server
 [grpc.filer]
 cert = ""
 key = ""
 allowed_commonNames = ""    # comma-separated SSL certificate common names
 
+# S3 server gRPC options (server-side)
+# Enables mTLS for incoming gRPC connections to S3 server
 [grpc.s3]
 cert = ""
 key = ""
@@ -130,36 +112,39 @@ cert = ""
 key = ""
 allowed_commonNames = ""    # comma-separated SSL certificate common names
 
-# use this for any place needs a grpc client
-# i.e., "weed backup|benchmark|filer.copy|filer.replicate|mount|s3|upload"
+# gRPC client configuration for outgoing gRPC connections
+# Used by clients (S3, mount, backup, benchmark, filer.copy, filer.replicate, upload, etc.)
+# when connecting to any gRPC server (master, volume, filer)
 [grpc.client]
 cert = ""
 key = ""
 
-# https client for master|volume|filer|etc connection
-# It is necessary that the parameters  [https.volume]|[https.master]|[https.filer] are set
+# HTTPS client configuration for outgoing HTTP connections
+# Used by S3, mount, filer.copy, backup, and other clients when communicating with master/volume/filer
+# Set enabled=true to use HTTPS instead of HTTP for data operations (separate from gRPC)
+# If [https.filer] or [https.volume] are enabled on servers, clients must have [https.client] enabled=true
 [https.client]
-enabled = false
-cert = ""
-key = ""
-ca = ""
+enabled = false  # Set to true to enable HTTPS for all outgoing HTTP client connections
+cert = ""        # Client certificate for mTLS (optional if server doesn't require client cert)
+key = ""         # Client key for mTLS (optional if server doesn't require client cert)
+ca = ""          # CA certificate to verify server certificates (required when enabled=true)
 
-# volume server https options
-# Configure these if you want the volume server to accept HTTPS connections
+# Volume server HTTPS options (server-side)
+# Enables HTTPS for incoming HTTP connections to volume server
 [https.volume]
 cert = ""
 key = ""
 ca = ""
 
-# master server https options
-# Configure these if you want the master server to accept HTTPS connections
+# Master server HTTPS options (server-side)
+# Enables HTTPS for incoming HTTP connections to master server (web UI, HTTP API)
 [https.master]
 cert = ""
 key = ""
 ca = ""
 
-# filer server https options
-# Configure these if you want the filer server to accept HTTPS connections
+# Filer server HTTPS options (server-side)
+# Enables HTTPS for incoming HTTP connections to filer server (web UI, HTTP API)
 [https.filer]
 cert = ""
 key = ""

Security-Overview.md

@@ -2,6 +2,39 @@
 
 Since SeaweedFS is a distributed system with many volume servers, the volume servers have the risk of being changed without proper access control. We want to have the freedom to place a volume server anywhere we want, with the confidence that nobody can tamper the data. 
 
+## Understanding Communication Layers
+
+SeaweedFS has two separate communication layers that must be secured independently:
+
+### gRPC Communication (Control Plane)
+Used for metadata operations and cluster coordination:
+- S3 ↔ Filer: Getting bucket info, file metadata
+- Filer ↔ Master: Getting volume assignments, cluster info
+- Volume ↔ Master: Heartbeats, volume management
+- **Configured via**: `[grpc.*]` sections in security.toml
+
+### HTTP/HTTPS Communication (Data Plane)
+Used for actual file data uploads/downloads:
+- S3/Filer/Client → Volume Server: Uploading and downloading actual file content
+- S3 → Filer: File data operations (when S3 acts as a proxy)
+- **Configured via**: `[https.*]` sections in security.toml
+
+### Configuration Sections Summary
+
+| Configuration Block | Purpose |
+|---------------------|---------|
+| `[grpc.client]` | Used by clients (S3, mount, filer.copy, backup, etc.) to connect to any gRPC server |
+| `[grpc.filer]`, `[grpc.master]`, `[grpc.volume]`, `[grpc.s3]` | Server-side gRPC mTLS - secures gRPC endpoints |
+| `[https.client]` | Client-side HTTPS configuration - tells clients (S3/Filer/etc.) to use HTTPS for HTTP connections |
+| `[https.volume]`, `[https.master]`, `[https.filer]` | Server-side HTTPS configuration - makes servers accept HTTPS connections |
+
+**Important**: 
+- `[https.client]` with `enabled = true` is required for clients to use HTTPS when connecting to HTTPS-enabled servers
+- If you enable `[https.filer]` on the Filer server, you must also enable `[https.client]` so that S3 API can connect via HTTPS
+- Otherwise, you'll get "client sent an HTTP request to an HTTPS server" errors
+
+## Security Features
+
 We will address the volume servers first. The following items are not covered, yet:
 - master server http REST services