From 8f3ef880c4db73fa40e9d8c5ef6cde296e20e3cb Mon Sep 17 00:00:00 2001
From: chrislusf <chris.lu@gmail.com>
Date: Tue, 25 Nov 2025 11:47:00 -0800
Subject: [PATCH] architecture

---
 S3-API-FAQ.md             | 23 +++++++++++++++++++++++
 Security-Configuration.md | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+)

diff --git a/S3-API-FAQ.md b/S3-API-FAQ.md
index ebc60da..1728369 100644
--- a/S3-API-FAQ.md
+++ b/S3-API-FAQ.md
@@ -231,4 +231,27 @@ aws s3 presign s3://test-bucket/test-object --endpoint-url https://yourdomain.co
 
 For detailed configuration examples, see the [[S3-Nginx-Proxy]] documentation.
 
+## TLS error: "client sent an HTTP request to an HTTPS server"
+
+SeaweedFS has two separate communication layers:
+- **gRPC (Control Plane)**: Metadata operations - configured via `[grpc.*]`
+- **HTTP/HTTPS (Data Plane)**: File data uploads/downloads - configured via `[https.*]`
+
+If you see this error when S3 API communicates with a TLS-enabled Filer, enable HTTPS client mode:
+
+```toml
+[https.filer]
+cert = "/path/to/filer.crt"
+key = "/path/to/filer.key"
+ca = "/path/to/ca.crt"
+
+[https.client]
+enabled = true
+cert = "/path/to/client.crt"
+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.
+
 
diff --git a/Security-Configuration.md b/Security-Configuration.md
index 5b78e96..7593b88 100644
--- a/Security-Configuration.md
+++ b/Security-Configuration.md
@@ -1,5 +1,34 @@
 
 
+# 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
+
 The first step is generating `security.toml` file via `weed scaffold -config=security`:
 
 ```
@@ -116,18 +145,21 @@ key = ""
 ca = ""
 
 # volume server https options
+# Configure these if you want the volume server to accept HTTPS connections
 [https.volume]
 cert = ""
 key = ""
 ca = ""
 
 # master server https options
+# Configure these if you want the master server to accept HTTPS connections
 [https.master]
 cert = ""
 key = ""
 ca = ""
 
 # filer server https options
+# Configure these if you want the filer server to accept HTTPS connections
 [https.filer]
 cert = ""
 key = ""