From 7321fa837f3b9de0c543d8b14a048f64b94ffb9c Mon Sep 17 00:00:00 2001
From: Chris Lu <chris.lu@gmail.com>
Date: Thu, 2 Apr 2026 11:40:53 -0700
Subject: [PATCH] Add S3 file permissions section to S3 Configuration page

Documents per-object ACL-to-file-mode mapping and the
-defaultFileMode / -s3.defaultFileMode server option.
---
 S3-Configuration.md | 58 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/S3-Configuration.md b/S3-Configuration.md
index c1af77d..53950d2 100644
--- a/S3-Configuration.md
+++ b/S3-Configuration.md
@@ -275,6 +275,64 @@ See [[Amazon IAM API]] for detailed IAM usage.
 
 ---
 
+## File Permissions for S3 Uploads
+
+By default, objects uploaded via S3 are created with Unix file mode `0660` (`-rw-rw----`). This can be controlled per-object via the `X-Amz-Acl` header, or overridden server-wide with the `-defaultFileMode` flag.
+
+### Per-Object Permissions via S3 ACL
+
+The `X-Amz-Acl` (canned ACL) header is mapped to Unix file permissions:
+
+| Canned ACL | File Mode | Permissions |
+|------------|-----------|-------------|
+| `private` | `0660` | `-rw-rw----` |
+| `public-read` | `0644` | `-rw-r--r--` |
+| `public-read-write` | `0666` | `-rw-rw-rw-` |
+| `authenticated-read` | `0644` | `-rw-r--r--` |
+| `bucket-owner-read` | `0644` | `-rw-r--r--` |
+| `bucket-owner-full-control` | `0660` | `-rw-rw----` |
+
+Example with rclone:
+
+```bash
+# Upload with world-readable permissions
+rclone copy myfile.txt remote:mybucket/ --s3-acl=public-read
+```
+
+Example with AWS CLI:
+
+```bash
+aws s3 cp myfile.txt s3://mybucket/ --acl public-read --endpoint-url http://localhost:8333
+```
+
+### Server-Wide Default File Mode
+
+To change the default for all uploads (when no ACL header is provided):
+
+```bash
+# Standalone S3 server
+weed s3 -defaultFileMode=0644
+
+# Embedded in weed server
+weed server -s3 -s3.defaultFileMode=0644
+
+# Embedded in weed filer
+weed filer -s3 -s3.defaultFileMode=0644
+
+# Mini mode
+weed mini -s3.defaultFileMode=0644
+```
+
+The value is an octal file mode string (e.g. `0644`, `0666`, `0660`).
+
+### Priority Order
+
+1. **Per-object `X-Amz-Acl` header** (if present and recognized)
+2. **Server-wide `-defaultFileMode`** (if configured)
+3. **Built-in default `0660`**
+
+---
+
 ## Related Documentation
 
 - [[S3 Credentials]] - Detailed documentation for basic credentials