Efficient Usage Collection
To manage quota, the system first needs to know how much storage currently used. Usually this would need some relatively complicated counting, rolling up the directory tree. One way is to count during write time, but the upper tree nodes would become hot spots. This would slow down the normal write operations.
Since SeaweedFS uses one collection for each bucket, the usage can be efficiently collected from the volumes used by the collection. So the usage collection is very cheap and does not interfere with write operations.
This page covers server-side bucket quota, enforced by an admin script that flips an over-quota bucket to read-only. It is distinct from the FUSE mount's
-collectionQuotaMB(used by the SeaweedFS CSI driver), which is enforced mount-side and fails writes withENOSPC.
How it works
There are two aspects of quota management: "quota configuration" and "quota enforcement".
- "Quota Configuration" is done in by an admin script in
weed shell, where you can set/remove/enable/disable bucket quota for each bucket. - "Quota Enforcement" is actually also an admin script, which you can run it periodically by adding it to
master.toml. It will check whether all the buckets are over their limit or not. If one bucket is over quota, it will set the bucket to read only.
The bucket's "readOnly" flag is checked when the filer processes write requests. If a bucket is readOnly, the creation and update requests on the bucket will be denied, except deletion. The read operations are not be affected.
Quota Configuration and Enforcement
1. View current bucket usage
Here there are 3 example buckets created. The bucket sizes and file counts are listed. The bucket size is the actual disk space used, including replicated copies.
> s3.bucket.list
b1 size:527971104 file:151
b2 size:468432 file:6
b3 size:10280 file:3
2. Set bucket "b1" to a low quota
> s3.bucket.quota -name b1 -sizeMB 15
updated quota for bucket b1
> s3.bucket.list
b1 size:527971104 file:151 quota:15728640 usage:3356.75%
b2 size:468432 file:6
b3 size:10280 file:3
3. Enforce the quota, and found it should be set to read only.
> s3.bucket.quota.enforce -apply
b1 size:527971104 quota:15728640 usage:3356.75%
changing bucket b1 to read only!
Note: Internally this readOnly flag is saved into filer configuration for locationPrefix="/buckets/b1/". So you could directly check the bucket readOnly property with fs.configure also.
> fs.configure
{
"locations": [
{
"locationPrefix": "/buckets/b1/",
"collection": "b1",
"readOnly": true
}
]
}
Over-quota writes (PutObject, UploadPart, CopyObject, UploadPartCopy) fail with 403 AccessDenied, not 500. Do not retry — the request cannot succeed until usage drops back under quota or the quota is raised.
Schedule Quota Enforcement
s3.bucket.quota.enforce -apply should be run regularly. You can add it to the master.toml file, or add it to some shell scripts. The frequency depends on how much you trust your users. :)
S3 API Extension (?seaweedfs-quota)
In addition to weed shell, bucket quota can be configured via the S3 API using a SeaweedFS-specific subresource. This is useful for programmatic integration (e.g., Apache CloudStack) where the integrator can sign SigV4 requests but cannot run weed shell.
API
PUT /{bucket}?seaweedfs-quota — set bucket quota (IAM: s3:PutBucketQuota)
GET /{bucket}?seaweedfs-quota — get bucket quota (IAM: s3:GetBucketQuota)
Request/response body (JSON):
{"quota_size": 100, "quota_unit": "GB", "quota_enabled": true}
Supported quota_unit values: B, KB, MB, GB, TB (case-insensitive).
quota_enabled: false with a positive quota_size stores the quota as disabled but retains the size. quota_size: 0 removes the quota entirely. When quota is cleared, the bucket's read-only flag is also lifted.
Authentication
Uses standard S3 SigV4 — the same credentials used for other S3 operations. No separate admin token is needed.
Authorization
Two dedicated IAM permissions:
s3:PutBucketQuota— required to set/clear quotas3:GetBucketQuota— required to read quota
This allows scoping a credential to quota management only, without granting bucket deletion, user management, or other admin capabilities.
Example (curl with SigV4)
Since ?seaweedfs-quota is a SeaweedFS extension and not part of the AWS S3 API, standard AWS tools (aws s3api, s3cmd, rclone) do not support it directly. Use any SigV4-capable HTTP client or sign the request manually:
# Set a 100GB quota on bucket "mybucket"
curl -X PUT \
-H "Content-Type: application/json" \
-H "Authorization: AWS4-HMAC-SHA256 ..." \
-d '{"quota_size":100,"quota_unit":"GB","quota_enabled":true}' \
http://localhost:8333/mybucket?seaweedfs-quota
# Get the current quota
curl -H "Authorization: AWS4-HMAC-SHA256 ..." \
http://localhost:8333/mybucket?seaweedfs-quota
Comparison with MinIO and Ceph
| Provider | Quota endpoint | Auth | CLI tool | aws s3api? |
|---|---|---|---|---|
| SeaweedFS | S3 API (?seaweedfs-quota) |
S3 SigV4 | weed shell |
No |
| MinIO | Admin API (separate) | Admin credentials | mc admin bucket quota |
No |
| Ceph RGW | Admin Ops API (/admin/) |
Admin capabilities | radosgw-admin quota set |
No |
None of the three use standard AWS S3 API for quota. SeaweedFS's approach is the closest to standard S3 because it uses the same endpoint and same SigV4 credentials, just with a custom query parameter.
Introduction
- Quick Start with weed mini
- Simplest S3 Bucket and User Setup
- Components
- Blob Store Architecture
- Getting Started
- Production Setup
- A typical step‐by‐step example
- Benchmarks
- FAQ
- Applications
API
Configuration
- Replication
- Store file with a Time To Live
- Failover Master Server
- Erasure coding for warm storage
- EC Bitrot Detection
- Server Startup via Systemd
- Environment Variables
Filer
- Filer Setup
- Directories and Files
- File Operations Quick Reference
- Data Structure for Large Files
- Filer Data Encryption
- Filer Commands and Operations
- Filer JWT Use
- TUS Resumable Uploads
Filer Stores
- Filer Cassandra Setup
- Filer Redis Setup
- Super Large Directories
- Path-Specific Filer Store
- Choosing a Filer Store
- Customize Filer Store
Management
Advanced Filer Configurations
- Migrate to Filer Store
- Add New Filer Store
- Filer Store Replication
- Filer Active Active cross cluster continuous synchronization
- Filer as a Key-Large-Value Store
- Path Specific Configuration
- Filer Change Data Capture
- Filer Operation Serialization
FUSE Mount
- Mount on Windows
- FIO benchmark
- fstab and systemd mount
- POSIX Compliance
- Distributed POSIX Locks
- P2P reading in weed mount
- Mount over the Internet
WebDAV
SFTP Server
Cloud Drive
- Cloud Drive Benefits
- Cloud Drive Architecture
- Configure Remote Storage
- Azure Blob Storage Authentication
- Mount Remote Storage
- Cache Remote Storage
- Cloud Drive Quick Setup
- Gateway to Remote Object Storage
AWS S3 API
- Amazon S3 API
- Supported APIs vs Minio
- S3 Lifecycle
- S3 Lifecycle vs Volume TTL
- S3 Conditional Operations
- S3 CORS
- S3 Object Lock and Retention
- S3 Object Versioning
- S3 RenameObject
- S3 API Benchmark
- S3 API FAQ
- S3 Bucket Quota
- S3 Rate Limiting
- S3 API Audit log
- S3 Nginx Proxy
- Docker Compose for S3
- Image Gateway
S3 Table Bucket
- S3 Table Bucket
- S3 Table Bucket Commands
- S3 Tables Security
- SeaweedFS Iceberg Catalog
- Iceberg REST Catalog API
- Iceberg Table Maintenance
- SeaweedFS Lance Catalog
- Lance Maintenance Worker
Iceberg Integrations
- Spark Iceberg Integration
- Trino Iceberg Integration
- Dremio Iceberg Integration
- DuckDB Iceberg Integration
- Doris Iceberg Integration
- RisingWave Iceberg Integration
- Lakekeeper Iceberg Integration
- OLake Go Iceberg Integration
Lance Integrations
S3 Authentication & IAM
- S3 Configuration - Start Here
- S3 Credentials (
-s3.config) - OIDC Integration (
-s3.iam.config) - Kubernetes ServiceAccount Authentication (IRSA-style)
- S3 Policy Variables
- S3 Policy Conditions
- S3 Bucket Policies
- Amazon IAM API
- AWS IAM CLI
- weed shell - Shell IAM Commands
Server-Side Encryption
S3 Client Tools
- AWS CLI with SeaweedFS
- s3cmd with SeaweedFS
- rclone with SeaweedFS
- restic with SeaweedFS
- nodejs with Seaweed S3
Machine Learning
HDFS
- Hadoop Compatible File System
- run Spark on SeaweedFS
- run HBase on SeaweedFS
- Run Trino on SeaweedFS
- Hadoop Benchmark
- HDFS via S3 connector
Replication and Backup
- Async Replication to another Filer [Deprecated]
- Async Backup
- Async Filer Metadata Backup
- Async Replication to Cloud [Deprecated]
- Kubernetes Backups and Recovery with K8up
Metadata Change Events
Messaging
- Structured Data Lake with SMQ and SQL
- Seaweed Message Queue
- SQL Queries on Message Queue
- SQL Quick Reference
- PostgreSQL-compatible Server weed db
- Pub-Sub to SMQ to SQL
- Kafka to Kafka Gateway to SMQ to SQL
Use Cases
Operations
- System Metrics
- weed shell
- Data Backup
- Deployment to Kubernetes and Minikube
- Helm Chart Recipes
- Deployment with seaweed-up
Rust Volume Server
Advanced
- Large File Handling
- Optimization
- Optimization for Many Small Buckets
- Volume Management
- Tiered Storage
- Cloud Tier
- Cloud Monitoring
- Load Command Line Options from a file
- SRV Service Discovery
- Volume Files Structure
Security
- Security Overview
- Security Configuration
- Cryptography and FIPS Compliance
- Run Blob Storage on Public Internet