Create: reference/rustfs.md

2026-04-15 20:58:55 -07:00
parent 566c96427a
commit c204f1d934
1 changed files with 495 additions and 0 deletions
@@ -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.*