RustFS Installation and Deployment

Download RustFS and select the version suitable for your system, supporting Windows, Linux, macOS, and Docker deployment. Start experiencing a high-performance distributed storage system.

MacOS

Homebrew Installation

1brew tap rustfs/homebrew-tap

2brew install rustfs

3rustfs --version

Binary Installation

Architecture: aarch64

1curl --progress-bar -O https://dl.rustfs.com/artifacts/rustfs/release/rustfs-macos-aarch64-latest.zip

2unzip rustfs-macos-aarch64-latest.zip

3chmod +x rustfs

4./rustfs --version

Architecture: x86_64

1curl --progress-bar -O https://dl.rustfs.com/artifacts/rustfs/release/rustfs-macos-x86_64-latest.zip

2unzip rustfs-macos-x86_64-latest.zip

3chmod +x rustfs

4./rustfs --version

Docker

Prerequisites

Host Requirements

iDocker (≥20.10) must be installed and able to pull images and run containersiLocal path /mnt/rustfs/data (or custom path) for mounting object data

Network and Firewall

iEnsure that port 9000 on the host is open to the outside (or custom port consistent)

Configuration File Preparation

iDefine listening port, admin account, data path, etc. in the host’s /etc/rustfs/config.toml

Pull Image Installation

1docker pull rustfs/rustfs:latest

2docker run -d \

3  --name rustfs \

4  -p 9000:9000 \

5  -p 9001:9001 \

6  -v /data:/data \

7  rustfs/rustfs:latest

Parameter descriptions:

i-p 9000:9000: maps the host’s 9000 Endpoint port to the containeri-p 9001:9001: maps the host’s 9001 Console port to the containeri-v /mnt/rustfs/data:/data: mounts the data volumei–name rustfs_local: custom name for the containeri-d: runs in the background

Complete Parameter Configuration

1docker run -d \

2  --name rustfs_container \

3  -p 9000:9000 \

4  -p 9001:9001 \

5  -v /mnt/rustfs/data:/data \

6  -e RUSTFS_ACCESS_KEY=rustfsadmin \

7  -e RUSTFS_SECRET_KEY=rustfsadmin \

8  -e RUSTFS_CONSOLE_ENABLE=true \

9  -e RUSTFS_SERVER_DOMAINS=example.com \

10  rustfs/rustfs:latest \

11  --address :9000 \

12  --console-enable \

13  --server-domains example.com \

14  --access-key rustfsadmin \

15  --secret-key rustfsadmin \

16  /data

Parameter Descriptions

Environment Variable Method (Recommended)

1-e RUSTFS_ADDRESS=:9000 \

2-e RUSTFS_SERVER_DOMAINS=example.com \

3-e RUSTFS_ACCESS_KEY=rustfsadmin \

4-e RUSTFS_SECRET_KEY=rustfsadmin \

5-e RUSTFS_CONSOLE_ENABLE=true \

Command Line Parameter Method

1--address :9000 \

2--server-domains example.com \

3--access-key rustfsadmin \

4--secret-key rustfsadmin \

5--console-enable \

Required Parameters

i: Specify at the end of the command, e.g.,/data

Common Configuration Combinations

Basic Configuration

1docker run -d \

2  -p 9000:9000 \

3  -p 9001:9001 \

4  -v /mnt/data:/data \

5  rustfs/rustfs:latest \

6  /data

Enable Console

1docker run -d \

2  -p 9000:9000 \

3  -p 9001:9001 \

4  -v /mnt/data:/data \

5  -e RUSTFS_CONSOLE_ENABLE=true \

6  rustfs/rustfs:latest \

7  --console-enable \

8  /data

Custom Authentication Keys

1docker run -d \

2  -p 9000:9000 \

3  -p 9001:9001 \

4  -v /mnt/data:/data \

5  -e RUSTFS_ACCESS_KEY=rustfsadmin \

6  -e RUSTFS_SECRET_KEY=rustfsadmin \

7  rustfs/rustfs:latest \

8  --access-key rustfsadmin \

9  --secret-key rustfsadmin \

10  /data

Notes

iPort mapping must correspondiDefault service port is 9000 (-p 9000:9000)iData volumes must be persistenti-v /host/path:/container/pathiEnvironment variables and command line parameters can be mixed, but command line parameters take precedenceiIf using TLS, you need to mount the certificate path separately

1-v /path/to/certs:/certs \

2-e RUSTFS_TLS_PATH=/certs \

Linux

Checklist

Hardware Requirements

Baseline Configuration Scheme

Component	Basic Environment	Production Standard Configuration	High-Performance Configuration
Number of Nodes	4 nodes	8 nodes	16+ nodes
Storage Medium	4× NVMe SSD	8× NVMe SSD	12× NVMe SSD
Network Architecture	Dual 25GbE (Link Aggregation)	Dual 100GbE	200GbE
CPU	2× Intel Silver 4310 (16 cores)	2× AMD EPYC 7313 (32 cores)	2× Intel Platinum 8461Y (48 cores)
Memory	64 GB DDR4-3200 ECC	256 GB DDR5-4800 ECC	512 GB DDR5-5600 ECC
Storage Controller	HBA 9500-8i	HBA 9600-16i	Dual Controller Redundant Architecture

Bandwidth and Disk Ratio

Network Type	Theoretical Throughput	Applicable Disk Types	Maximum Disk Support Count
10GbE	1.25 GB/s	7.2K HDD (180 MB/s)	8 disks
25GbE	3.125 GB/s	SATA SSD (550 MB/s)	6 disks
100GbE	12.5 GB/s	NVMe Gen4 (7 GB/s)	2 disks at full read/write speed

Best Practice Case: A video platform uses a 16-node cluster, with each node configured as follows:

i8×7.68 TB NVMe SSDiDual 100GbE CX5 network cardsiAchieving an aggregated throughput of 38 GB/s

Memory Configuration Calculation

Data Scale	Read Intensive	Write Intensive	Mixed
10 TB	40 GB	44 GB	42 GB
100 TB	112 GB	152 GB	132 GB
500 TB	432 GB	632 GB	532 GB

Hardware Selection

Testing Environment

The testing environment can be quickly used without being responsible for high load and production assurance, just meeting experimental needs.

No.	Hardware Type	Parameters
1	CPU	1 core+
2	CPU Architecture	X86, ARM are both acceptable
3	Memory	1 GB+
4	Disk	HDD, SSD are both acceptable
5	Docker Support	Supported
6	Network Requirements	Local communication and no network are acceptable
7	Operating System	Windows, Linux, MacOS are all acceptable
8	Load Balancing	None
9	Minimum Nodes	1

Production Environment

No.	Hardware Type	Parameters
1	CPU	2 × 12 cores+
2	CPU Type	Multiple CPU architectures such as X86, ARM
3	Memory	64 GB+
4	Disk	HDD, SSD are both acceptable, SSD is recommended
5	Network Requirements	10 Gbps+
6	Operating System	Linux preferred
8	Load Balancing	Load balancing is recommended
9	Minimum Nodes	At least 4 nodes

Network Check

Kernel Parameter Tuning

1# Check the following parameter settings

2net.core.rmem_max = 16777216

3net.core.wmem_max = 16777216

4net.ipv4.tcp_keepalive_time = 600

5net.ipv4.tcp_slow_start_after_idle = 0

Firewall Rules

1# Necessary open ports

2- TCP 443 (HTTPS API)

3- TCP 9000 (S3 compatible interface)

4- TCP 7946 (Serf node communication)

5- UDP 4789 (VxLAN tunnel)

Software Check

iOperating System: It is recommended to use a long-term support version of Linux (such as Ubuntu 20.04+/22.04, RHEL 8/9, etc.), with a kernel version preferably 5.x or higher. RustFS can utilize io_uring asynchronous I/O optimization under Linux 5.x+ kernel, providing better throughput performance.iCPU & Memory: Supports mainstream CPU architectures such as x86_64, ARM. The testing environment requires at least 2 GB of memory, while the production environment is recommended to have at least 64 GB of memory (Linux installation of RustFS). Don’t forget to estimate the required memory based on data scale and concurrency to avoid performance bottlenecks due to insufficient memory.iDisable Interfering Services: To ensure performance, it is recommended to disable or ignore services that scan/audit the file system (such as mlocate, plocate, updatedb, auditd, antivirus software, etc.), as these services may conflict with RustFS’s disk I/O. If they cannot be disabled, exclude RustFS’s data path from scanning to avoid performance impact.

It is recommended to use versions with a 5.x kernel from mainstream enterprise distributions, such as:

iUbuntu 20.04 LTS (can install HWE kernel to obtain 5.15+)iUbuntu 22.04 LTS (default 5.15+)iCentOS Stream 9 / RHEL 9 iDebian 12 (default 6.x, stronger) iIf you are still using an old kernel (such as 4.x), it is recommended to upgrade or use a distribution that supports custom kernels to fully leverage RustFS’s performance advantages.

Security Check

Authentication and Access Control

iUse S3 compatible key authentication. RustFS uses a signature mechanism similar to AWS Signature V4 for authentication. Each user or service must access using a valid Access Key and Secret Key, and never skip the authentication step.iPolicy-based Access Control: Define access policies for different roles and users according to the principle of least privilege. Group policies and user policies can be set to specify allowed S3 operations. By default, operations not explicitly authorized in the policy should be denied.

Environment Variables and Credential Protection

iChange Default Credentials: If using the default account (such as rustfsadmin / rustfsadmin) during RustFS initialization, it must be changed to a randomly complex password after deployment.iSecurely Store Credentials: Do not hard-code plaintext passwords in scripts, images, or logs. Use environment variables or Kubernetes Secrets to manage passwords.

API Access Restrictions

iLimit Network Access: By default, RustFS’s S3 API listens on port 9000, and the management console listens on port 9090. Limit access source IPs through firewalls or cloud security groups.iNetwork Isolation and Proxy: It is recommended to expose services through a reverse proxy (such as Nginx) to avoid directly exposing storage node IPs.iClose Unnecessary Ports: Disable unused ports or interfaces, such as not exposing the management interface to the public.

Single Machine Single Disk Installation

Single machine single disk is suitable for low-density non-critical business. In production environments, it is recommended to perform data backups to avoid data risks.

There is only one data disk in the server, and all data falls into this one data disk.

Download Installation Package

Please first installwget or curl to download the rustfs installation package.

1# Download address

2wget https://dl.rustfs.com/artifacts/rustfs/release/rustfs-linux-x86_64-musl-latest.zip

3unzip rustfs-linux-x86_64-musl-latest.zip

4chmod +x rustfs

5mv rustfs /usr/local/bin/

Configure Environment Variables

Create Configuration File

1# Single machine single disk mode

2sudo tee /etc/default/rustfs <

<pre><code>3RUSTFS_ACCESS_KEY=rustfsadmin

4RUSTFS_SECRET_KEY=rustfsadmin

5RUSTFS_VOLUMES="/data/rustfs0"

6RUSTFS_ADDRESS=":9000"

7RUSTFS_CONSOLE_ENABLE=true

8RUST_LOG=error

9RUSTFS_OBS_LOG_DIRECTORY="/var/logs/rustfs/"

10EOF

<h5><span><span>Create Storage Directory</span></span></h5><pre><code class="language-plaintext">1sudo mkdir -p /data/rustfs0 /var/logs/rustfs /opt/tls

2sudo chmod -R 750 /data/rustfs* /var/logs/rustfs

Configure System Service

Create systemd Service File

1sudo tee /etc/systemd/system/rustfs.service <

<pre><code>2[Unit]

3Description=RustFS Object Storage Server

4Documentation=https://rustfs.com/docs/

5After=network-online.target

6Wants=network-online.target

7[Service]

8Type=notify

9NotifyAccess=main

10User=root

11Group=root

12WorkingDirectory=/usr/local

13EnvironmentFile=-/etc/default/rustfs

14ExecStart=/usr/local/bin/rustfs $RUSTFS_VOLUMES

15LimitNOFILE=1048576

16LimitNPROC=32768

17TasksMax=infinity

18Restart=always

19RestartSec=10s

20OOMScoreAdjust=-1000

21SendSIGKILL=no

22TimeoutStartSec=30s

23TimeoutStopSec=30s

24NoNewPrivileges=true

25ProtectSystem=full

26ProtectHome=true

27PrivateTmp=true

28PrivateDevices=true

29ProtectClock=true

30ProtectKernelTunables=true

31ProtectKernelModules=true

32ProtectControlGroups=true

33RestrictSUIDSGID=true

34RestrictRealtime=true

35# service log configuration

36StandardOutput=append:/var/logs/rustfs/rustfs.log

37StandardError=append:/var/logs/rustfs/rustfs-err.log

38[Install]

39WantedBy=multi-user.target

40EOF

<h5><span><span>Reload Service Configuration</span></span></h5><pre><code class="language-plaintext">1sudo systemctl daemon-reload

Start Service and Verify

1Start the service and set it to start on boot

1sudo systemctl enable --now rustfs

1Verify Service Status

1systemctl status rustfs

1Check Service Ports

1netstat -ntpl

1View Log Files

1tail -f /var/logs/rustfs/rustfs*.log

1Access the Management Console

1http://127.0.0.1:9001

Single Machine Multi-Disk Installation

Basically refer to the single machine single disk installation method, only the configuration of environment variables is slightly different, then restart the service.

Configure Environment Variables

Create Configuration File

Key focus: RUSTFS_VOLUMES=”/data/rustfs{0…3}”

1# Single machine multi-disk mode

2sudo tee /etc/default/rustfs <

<pre><code>3RUSTFS_ACCESS_KEY=rustfsadmin

4RUSTFS_SECRET_KEY=rustfsadmin

5RUSTFS_VOLUMES="/data/rustfs{0...3}"

6RUSTFS_ADDRESS=":9000"

7RUSTFS_CONSOLE_ENABLE=true

8RUST_LOG=error

9RUSTFS_OBS_LOG_DIRECTORY="/var/logs/rustfs/"

10EOF

<h5><span><span>Create Storage Directory</span></span></h5><blockquote><p><span><span>Key focus:</span></span><span><span> mkdir -p /data/rustfs{0..3}</span></span></p></blockquote><pre><code class="language-plaintext">1sudo mkdir -p /data/rustfs{0..3} /var/logs/rustfs /opt/tls

2sudo chmod -R 750 /data/rustfs* /var/logs/rustfs

Multi-Machine Multi-Disk Installation

At least 4 servers are required, with a minimum of 1 disk per server, to safely start the distributed object storage cluster.

Hostnames

Creating a RustFS cluster must use the same, continuous hostnames. There are two ways to achieve continuous hostnames:

DNS Configuration:

Please configure your DNS resolution server to ensure the continuity of names.

HOSTS Configuration:

Modify the local alias settings in /etc/hosts, the specific operation is as follows:

1vim /etc/hosts

2127.0.0.1 localhost localhost.localdomain localhost4 localhost4.localdomain4

3::1 localhost localhost.localdomain localhost6 localhost6.localdomain6

4192.168.1.1 node1

5192.168.1.2 node2

6192.168.1.3 node3

7192.168.1.4 node4

Memory Conditions

RustFS requires at least 2 GB of memory to run the testing environment, while the production environment requires a minimum of 128 GB of memory.

Time Synchronization

Consistency across multiple nodes must use a time server to maintain time consistency, otherwise, it may result in the inability to start services. Related time servers include ntp, timedatectl, or timesyncd.

RustFS requires time synchronization, you can check the time synchronization status with the following command:

1timedatectl status

If the status is “synchronized”, it indicates that time synchronization is normal.

Capacity and EC Planning

When planning object storage capacity, it is recommended to consider:

iInitial Data Volume: How much data do you plan to migrate or store at once? (e.g., 500 TB)iData Growth: Daily/weekly/monthly data growth capacity;iPlanning Cycle: How long do you want this hardware planning to last? (Recommendation: 3 years)iConsider your company’s hardware iteration and update cycle.

EC (Erasure Coding) planning is as follows:

Scenario	Recommended Check Level	Description
Standard Production Environment	EC:4	Can tolerate up to 4 disk (or node) failures, achieving a good balance between reliability and storage efficiency.
High Availability Requirements	EC:4 – 8 or higher	Suitable for scenarios with extremely high data availability requirements, but sacrifices more storage space.
Development Testing Environment	EC:2	Provides basic redundancy protection, suitable for non-critical business.

Installation

Basically refer to the single machine single disk installation method, only the configuration of environment variables is slightly different, then restart the service.

Create Configuration File

Key focus: RUSTFS_VOLUMES=”http://node{1…4}:9000/data/rustfs{0…3}”

1# Multi-machine multi-disk mode

2sudo tee /etc/default/rustfs <

<pre><code>3RUSTFS_ACCESS_KEY=rustfsadmin

4RUSTFS_SECRET_KEY=rustfsadmin

5RUSTFS_VOLUMES="http://node{1...4}:9000/data/rustfs{0...3}"

6RUSTFS_ADDRESS=":9000"

7RUSTFS_CONSOLE_ENABLE=true

8RUST_LOG=error

9RUSTFS_OBS_LOG_DIRECTORY="/var/logs/rustfs/"

10EOF

<h2><span><span>Reference Documents</span></span></h2>i<span><span>[Linux Installation](https://docs.rustfs.com/zh/installation/linux/)</span></span>i<span><span>[Docker Installation](https://docs.rustfs.com/zh/installation/docker/)</span></span>