vh/VuongKB
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Create: reference/rustfs.md

Browse Source
This commit is contained in:
Atlas
2026-04-15 20:58:55 -07:00
parent 566c96427a
commit c204f1d934
1 changed files with 495 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
reference/rustfs.md
+495
View File
@@ -0,0 +1,495 @@
---
created: '2026-04-16T03:58:55+00:00'
id: c724b70a-3a92-4527-82a8-22a64533adee
keywords:
- RustFS
- object storage
- S3 compatible
- Rust
- erasure coding
- Reed-Solomon
- distributed storage
- docker
- kubernetes
- MinIO client
- mc
- AWS S3 SDK
- Apache 2.0
- Blake3
- Rayon
- AVX2
- WORM
- federation
- multi-cloud gateway
- SNSD
- SNMD
- MNMD
links: []
modified: '2026-04-16T03:58:55+00:00'
summary: Comprehensive reference for RustFS, a high-performance distributed object
storage system written in Rust. Covers architecture, installation, S3 compatibility,
erasure coding, SDKs, management, and usage limits.
tags:
- rustfs
- object-storage
- s3
- distributed-storage
- docker
- kubernetes
- rust
- devops
- reference
title: RustFS — High-Performance Distributed Object Storage
---
---
id: reference/rustfs
title: "RustFS — High-Performance Distributed Object Storage"
created: 2025-07-10
modified: 2025-07-10
tags:
- rustfs
- object-storage
- s3
- distributed-storage
- docker
- kubernetes
- rust
- devops
- reference
keywords:
- RustFS
- object storage
- S3 compatible
- Rust
- erasure coding
- Reed-Solomon
- distributed storage
- docker
- kubernetes
- MinIO client
- mc
- AWS S3 SDK
- Apache 2.0
- Blake3
- Rayon
- AVX2
- WORM
- federation
- multi-cloud gateway
- SNSD
- SNMD
- MNMD
links:
- "[[reference/docker-compose]]"
---
# RustFS — High-Performance Distributed Object Storage
> **Official documentation:** <https://docs.rustfs.com>
> **License:** Apache 2.0 (commercially friendly)
> **Repository:** `git@github.com:rustfs/rustfs.git`
> **Docker image:** `rustfs/rustfs`
RustFS is a high-performance, distributed object storage solution designed for simplicity and efficiency. Fully compatible with the S3 protocol, it is open-source software built with Rust — leveraging industry-leading memory safety and zero-cost abstractions to deliver exceptional performance comparable to C/C++.
It serves as a modern alternative to legacy object storage solutions, offering a robust platform for data-intensive applications.
---
## Table of Contents
- [Overview & Features](#overview--features)
- [Architecture](#architecture)
- [Installation](#installation)
- [Deployment Modes](#deployment-modes)
- [Docker Quick Start](#docker-quick-start)
- [Docker Compose Deployment](#docker-compose-deployment)
- [Production Recommendations](#production-recommendations)
- [S3 Compatibility](#s3-compatibility)
- [Erasure Coding](#erasure-coding)
- [Bare Metal & Virtualized Deployment](#bare-metal--virtualized-deployment)
- [Enterprise Features](#enterprise-features)
- [SDKs & Client Libraries](#sdks--client-libraries)
- [MinIO Client (mc) Reference](#minio-client-mc-reference)
- [Usage Limits](#usage-limits)
- [Platform & OS Support](#platform--os-support)
- [Documentation Map](#documentation-map)
- [Related](#related)
---
## Overview & Features
| Feature | Detail |
|---|---|
| **S3 Compatible** | Fully compatible with the S3 API (V2 and V4) |
| **Distributed Architecture** | Horizontal scaling, symmetric nodes |
| **License** | Apache v2.0 — commercially friendly |
| **Language** | Rust — memory safety, zero-cost abstractions |
| **Performance** | Comparable to C/C++ |
| **Security** | Rust memory safety guarantees, TLS, AES-256-GCM, KMS integration |
| **Cross-Platform** | Linux, macOS, Windows, FreeBSD, Docker, edge gateways |
| **Extensible** | Plugin architecture |
| **Cloud-Native** | Docker and Kubernetes optimized |
| **Single Binary** | ~100 MB static binary |
**Vision:** Provide the storage foundation for the AI era, enabling every personal AI agent to securely store and access data.
---
## Architecture
RustFS uses a **fully symmetric architecture** — all servers are functionally equal. There are no name nodes or metadata servers. Data and metadata are written atomically. Key architectural characteristics:
- **One process per node** with lightweight coroutines for high concurrency.
- **Erasure sets** group drives (default: 16 drives/set) with deterministic hashing for object placement.
- **Inline operations:** erasure coding, bitrot checking, and encryption are strictly consistent — applied before the write acknowledgment is returned.
- **Single-layer software-defined design** running on industry-standard hardware (JBOD/JBOF commodity servers).
- **Lightweight containers** suitable for Kubernetes deployment.
- **Multi-datacenter** support: each tenant runs an isolated cluster; independent scaling via federation across geographies.
### S3 Ports
| Port | Purpose |
|---|---|
| `9000` | S3 API |
| `9001` | Console UI |
---
## Installation
### Deployment Modes
RustFS supports three installation modes, each suited to different scales:
| Mode | Abbreviation | Use Case | Redundancy |
|---|---|---|---|
| **Single Node, Single Disk** | SNSD | Local testing, small-scale | None — zero erasure coding |
| **Single Node, Multiple Disk** | SNMD | Development, moderate workloads | Erasure coding across local disks |
| **Multiple Node, Multiple Disk** | MNMD | Enterprise-grade production | Full erasure coding + distributed redundancy |
> **Pre-installation checks** are recommended. RustFS runs on almost any CPU/OS (x86, ARM).
### Docker Quick Start
**Prerequisites:** Docker ≥ 20.10, port 9000 open.
```bash
docker pull rustfs/rustfs
docker run -d \
--name rustfs_local \
-p 9000:9000 \
-p 9001:9001 \
-v /mnt/rustfs/data:/data \
rustfs/rustfs:latest \
/data
```
The container runs as a non-root user `rustfs` (UID `10001`).
#### Environment Variables
| Variable | Default | Description |
|---|---|---|
| `RUSTFS_ADDRESS` | `:9000` | S3 API bind address |
| `RUSTFS_SERVER_DOMAINS` | — | Server domain(s) |
| `RUSTFS_ACCESS_KEY` | `rustfsadmin` | Access key |
| `RUSTFS_SECRET_KEY` | `rustfsadmin` | Secret key |
| `RUSTFS_CONSOLE_ENABLE` | `true` | Enable Console UI on port 9001 |
Command-line parameters are also supported and take **higher priority** than environment variables.
### Docker Compose Deployment
> For the full Docker Compose reference, see **[Docker Compose Deployment](/reference/docker-compose)**.
```bash
# Clone the repository
git clone git@github.com:rustfs/rustfs.git
# Start with observability stack (Grafana, Prometheus, Jaeger, OpenTelemetry Collector)
docker compose --profile observability up -d
# Start RustFS only (no observability)
docker compose -f docker-compose.yml up -d rustfs
```
The observability profile starts: **rustfs-server**, **Grafana**, **Prometheus**, **Jaeger**, and **otel-collector**.
#### Default Credentials
| Method | Username | Password |
|---|---|---|
| Environment variables | `rustfsadmin` | `rustfsadmin` |
| Some documentation | `rustfsadmin` | `ChangeMe123!` |
#### TLS Support
Mount certificates and set `RUSTFS_TLS_PATH` to enable TLS.
### Production Recommendations
- Deploy **multi-node** for redundancy and performance.
- Enable **TLS** for all connections.
- Configure **log rotation**.
- Establish a **backup strategy**.
- Use **local SSD/NVMe** storage.
- **Avoid NFS** — use direct-attached storage.
---
## S3 Compatibility
RustFS maintains strict adherence to S3 API standards, supporting **API V2 and V4** with location-independent compatibility across:
- Public cloud
- Private cloud
- Data center
- Multi-cloud
- Hybrid cloud
- Edge deployments
### Core S3 Features
- **S3 Select:** SIMD-optimized queries on CSV, Parquet, and JSON data.
- **AWS Signature Version 4:** Policy-based access control compatible with AWS IAM.
- **Broad ecosystem support:** GitHub/GitLab, MongoDB, ClickHouse, MariaDB, CockroachDB, Teradata, KubeFlow, TensorFlow.
---
## Erasure Coding
RustFS uses **Reed-Solomon (RS) Code** based on finite field algebraic structures.
### Key Parameters
| Parameter | Meaning |
|---|---|
| **k** | Original data shards |
| **m** | Parity shards |
| **n** | Total shards (k + m) |
Any **k** of **n** shards are sufficient to recover the original data. Recovery uses Gaussian elimination or FFT.
### Example: RS(10, 4)
- **Fault tolerance:** 4 nodes
- **Storage utilization:** 71% (vs 33% for triple replication)
### RustFS Implementation Details
| Component | Detail |
|---|---|
| **Shard size** | Dynamic, 64 KB – 4 MB |
| **Hash checksum** | Blake3 algorithm |
| **Parallel encoding** | Rayon framework + AVX2 SIMD instructions |
| **Finite field** | GF(2⁸) with generator polynomial `0x11D` |
| **Tiering** | Runtime (k, m) adjustment for hot/warm/cold tiers |
| **Max parity** | N/2 |
---
## Bare Metal & Virtualized Deployment
RustFS is software-defined, runs on industry-standard hardware, and requires no special storage appliances.
### Key Capabilities
| Feature | Detail |
|---|---|
| **Bitrot Protection** | HighwayHash, READ/WRITE verification, >10 GB/s hash speed on single core |
| **Server-Side Encryption** | AES-256-GCM, ChaCha20-Poly1305, AES-CBC; AEAD encryption; KMS integration (HashiCorp Vault); SSE-S3 support |
| **WORM** | Write Once Read Many — disables all mutation APIs; for regulatory compliance |
| **Identity Management** | OpenID Connect, external IdP integration, temporary rotated passwords, fine-grained access policies |
| **Continuous Replication** | Lambda-based notifications for immediate change propagation; cross-datacenter, multi-vendor |
| **Global Federation** | Unified namespace across distributed mode sets; unlimited mode sets per federation; single console administration |
| **Multi-Cloud Gateway** | S3 API view regardless of data location; makes non-S3 storage appear S3-compatible |
---
## Enterprise Features
- **Object Lock & Read-Only:** Compliance and governance modes.
- **Cross-Region Replication:** Active-active and active-passive.
- **Version Control:** Configurable version limits.
- **Lifecycle Management:** Automated tiering and expiration policies.
- **Log Management:** Structured logging with observability integration.
- **Encryption:** At-rest and in-transit with KMS support.
---
## SDKs & Client Libraries
### Management Interfaces
1. **Console UI** — web-based (port 9001)
2. **MinIO Client (mc)** — CLI tool
3. **SDKs** — programmatic access
### Available SDKs
| Language | Recommended SDK |
|---|---|
| Java | Official AWS S3 SDK for Java |
| JavaScript | Official AWS S3 SDK for JavaScript |
| Python | Official AWS S3 SDK for Python (boto3) |
| Rust | Official AWS S3 SDK for Rust |
| TypeScript | Official AWS S3 SDK for TypeScript |
| Golang | Official AWS S3 SDK for Go |
> **Recommendation:** Use the **official AWS S3 SDKs** — they are mature, well-maintained, and highly optimized. RustFS is fully compatible. Fully compatible with MinIO SDKs as well (just change Endpoint, AK, SK). Avoid non-S3-compliant third-party SDKs.
---
## MinIO Client (mc) Reference
### Setup
```bash
mc alias set rustfs http://12.34.56.78:9000 ACCESS_KEY SECRET_KEY
```
### Common Operations
```bash
mc ls rustfs # List buckets
mc mb rustfs/mybucket # Create bucket
mc rb rustfs/mybucket # Delete bucket
mc cp localfile.txt rustfs/mybucket # Upload object
mc rm rustfs/mybucket/localfile.txt # Delete object
mc get rustfs/mybucket/localfile.txt . # Download object
```
### Quick Verification
```bash
mc alias set rustfs http://localhost:9000 rustfsadmin ChangeMe123!
mc mb rustfs/mybucket
mc ls rustfs
```
---
## Usage Limits
### S3 API Limits
| Resource | Limit |
|---|---|
| Max object size | 5 TiB |
| Min object size | 0 B |
| Single PUT max (non-multipart) | 500 GiB |
| Multipart upload max | 5 TiB |
| Max parts per upload | 10,000 |
| Part size range | 5 MiB – 5 GiB (last part: 0 – 5 GiB) |
| Max list objects per request | 1,000 |
| Bucket name max length | 63 characters |
| Object name max length | 1,024 characters |
| Object name segment max (per `/`) | 255 characters |
| Max versions per object | 10,000 (configurable) |
### Erasure Coding Limits
| Resource | Limit |
|---|---|
| Max servers per cluster | No hard limit |
| Max drives per server | No hard limit |
| Min servers | 1 (SNSD — no redundancy) |
| Read quorum | N/2 |
| Write quorum | (N/2) + 1 |
### Naming Conventions
- **Production recommendation:** Linux + XFS filesystem.
- Avoid special characters on Windows.
- Do not create objects whose names conflict with parent or sibling prefixes.
---
## Platform & OS Support
| Platform | Supported |
|---|---|
| Linux | ✅ |
| Unix | ✅ |
| Windows | ✅ |
| macOS | ✅ |
| FreeBSD | ✅ |
| Docker | ✅ |
| Edge gateways | ✅ |
**CPU architectures:** x86, ARM, and others.
---
## Documentation Map
Reference structure of the official RustFS documentation at <https://docs.rustfs.com>:
### Installation
- [Linux (SNSD / SNMD / MNMD)](https://docs.rustfs.com/installation/linux/)
- [Windows](https://docs.rustfs.com/installation/)
- [macOS](https://docs.rustfs.com/installation/)
- [Docker](https://docs.rustfs.com/installation/docker/)
- Installation Checklist: Hardware, Network, Software, Security
### Performance
- Comparison, Design Architecture, Terminology, Usage Limits
### Core Concepts
- [Erasure Coding](https://docs.rustfs.com/concepts/principle/erasure-coding.html)
- [Introduction](https://docs.rustfs.com/concepts/introduction.html)
### Management
- Bucket (creation/deletion)
- Object (upload/deletion/scanner)
- IAM (access tokens)
- Upgrade / Expansion / Uninstallation
- Troubleshooting: Disk Failure, Object Healing, Node Failure
### Integration
- Nginx Reverse Proxy
- Virtual Host Mode
- TLS Configuration
### Developer
- MCP
- [MinIO Client (mc)](https://docs.rustfs.com/developer/mc.html)
- [SDKs](https://docs.rustfs.com/developer/sdk/) (Java, Python, Rust, JS, TS, Go)
- [S3 Compatible API](https://docs.rustfs.com/features/s3-compatibility/)
### Features
- [Distributed Architecture](https://docs.rustfs.com/features/distributed/)
- [Bare Metal & Virtualized Deployment](https://docs.rustfs.com/features/baremetal)
- Log Management
- Version Control
- S3 Compatibility
- Object Lock & Read-Only
- Cross-Region Replication
- Encryption
- Lifecycle Management
### Solutions
- Modern Data Lake
- AI / ML
- Cloud Native
- Big Data — Compute/Storage Separation
- SQL Support
- Quantitative Trading
- Manufacturing Cost Reduction
- Cold Archive
- Video Storage
- Domestic Innovation
---
## Related
- **[Docker Compose Deployment](/reference/docker-compose)** — Docker Compose deployment patterns and configuration reference, including the RustFS observability stack.
---
*Source: <https://docs.rustfs.com> — official RustFS documentation.*