Add S3 file permissions section to S3 Configuration page

Documents per-object ACL-to-file-mode mapping and the
-defaultFileMode / -s3.defaultFileMode server option.
Chris Lu committed 2026-04-02 11:40:53 -07:00
1 parent 7cacae6546
commit 7321fa837f
1 file changed
+58
+58
@@ -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