From 3f1a34d8d7ce9229ce7951baac24f19e59e7d4b0 Mon Sep 17 00:00:00 2001
From: chrislu <chris.lu@gmail.com>
Date: Tue, 25 Nov 2025 11:59:36 -0800
Subject: [PATCH] doc

---
 weed/command/scaffold/security.toml | 46 +++++++++++++++++++----------
 1 file changed, 31 insertions(+), 15 deletions(-)

diff --git a/weed/command/scaffold/security.toml b/weed/command/scaffold/security.toml
index 10f472d81..f18df202c 100644
--- a/weed/command/scaffold/security.toml
+++ b/weed/command/scaffold/security.toml
@@ -56,29 +56,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 = ""
@@ -109,40 +118,47 @@ 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]|[https.admin] 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
+# Volume server HTTPS options (server-side)
+# Enables HTTPS for incoming HTTP connections to volume server
 [https.volume]
 cert = ""
 key = ""
 ca = ""
 
-# master server https options
+# 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
+# Filer server HTTPS options (server-side)
+# Enables HTTPS for incoming HTTP connections to filer server (web UI, HTTP API)
 [https.filer]
 cert = ""
 key = ""
 ca = ""
 # disable_tls_verify_client_cert = true|false (default: false)
 
-# admin server https options
+# Admin server HTTPS options (server-side)
+# Enables HTTPS for incoming HTTP connections to admin server
 [https.admin]
 cert = ""
 key = ""