VuongKB/reference/rustfs.md

---
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.*