diff --git a/reference/rustfs.md b/reference/rustfs.md new file mode 100644 index 0000000..982bdba --- /dev/null +++ b/reference/rustfs.md @@ -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:** +> **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 : + +### 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: — official RustFS documentation.* \ No newline at end of file