Skip to content

S3 Object Storage

gitsync edited this page Nov 17, 2026 · 7 revisions

Overview

ZNAS includes an optional S3-compatible object server: RustFS (open source, Apache-2.0). When it is installed, the portal manages the server, its configuration, S3 users and buckets entirely from the web UI.

MinIO was replaced by RustFS in ZNAS 6.10.17. MinIO's open-source edition is end of life: its server and client repositories are archived and no binaries are published any more. See Moving from MinIO below if your server ran MinIO.

The S3 Buckets nav item appears once RustFS is installed. The nav dot turns:

  • Green — service is active and buckets exist
  • Red — service is down but buckets exist

Install

Go to Requisites → Optional Features and click Enable S3 Object Server on the S3-compatible object storage server row (Debian and Ubuntu).

ZNAS downloads the pinned RustFS release from GitHub, checks it against a SHA-256 checksum built into ZNAS (a download that does not match is refused), installs /usr/local/bin/rustfs, and creates the rustfs system account and service. Nothing else is installed: users, buckets and permissions are managed by ZNAS directly through the S3 and admin APIs.

On hardened servers, re-apply the sudoers template once (Requisites → Hardening): the S3 rules are in the ZFSNAS_S3 group.


Setup

Go to Sharing → S3 Buckets and click Configure:

Field Description
Backend dataset ZFS dataset that stores the objects. RustFS keeps them in a rustfs-data folder inside it, owned by the rustfs account
API port S3 API port (default 9000)
Console port RustFS web console port (default 9001)
Admin user / password The S3 server's administrator (RUSTFS_ACCESS_KEY / RUSTFS_SECRET_KEY), separate from portal accounts. Leave the password blank to keep the current one
Region AWS-style region name (default us-east-1)
Site name Optional label shown in ZNAS
Server URL Optional public URL (e.g. https://s3.example.com). Its host name enables virtual-hosted-style requests (bucket.s3.example.com)
TLS HTTPS on both ports, with a generated self-signed certificate (valid for the host name and every local IP) or one of the portal's certificates

Save & Apply writes the configuration and (re)starts the service. RustFS Console opens the server's own web console (http(s)://<server>:9001/rustfs/console/), where you sign in with the admin user.


S3 users

S3 users are the server's own accounts, separate from portal users.

Operation Description
Add Create a user with an access key and a secret key (8+ characters)
Enable / Disable Turn a user's access off without deleting it
Change password Set a new secret key; the user's bucket access is kept
Delete Remove the user (and it from every bucket's user list)

S3 buckets

Field Description
Name 3–63 characters: lowercase letters, digits, hyphens
Comment Optional description
Versioning Off, Enabled (keep every version) or Suspended
Object lock Write-once (WORM) bucket; requires versioning. Set at creation only
Quota Hard size limit, e.g. 500G or 2T (empty = none)
Anonymous access Private, Public Read (anyone can download) or Public (anyone can also upload and delete)
Users S3 users who get read/write access to this bucket (through a zfsnas-<bucket> policy)

Deleting a bucket deletes everything in it, every object version included.


Service management

Click the status badge next to S3 Buckets to Start, Stop or Restart RustFS.

To remove the server, use the ⋮ menu of its row in Requisites → Optional Features → Uninstall. The binary, service and settings file are removed; the data stays on the dataset, and installing RustFS again (same dataset, same admin user) brings the buckets, objects and users back.


Moving from MinIO

RustFS cannot read MinIO's storage format, so a server that ran MinIO starts RustFS with no buckets:

  • the first Save & Apply on RustFS switches the MinIO service off for good and starts RustFS in a new rustfs-data folder;
  • the old buckets are listed in a notice on the S3 page; their data is untouched in the minio-data folder of the dataset;
  • to bring the data over, start the old MinIO once more on another port and copy each bucket with an S3 tool, e.g. rclone sync oldminio:bucket znas:bucket (rclone provider Other for RustFS).

Connecting clients

RustFS speaks the standard S3 API. Use path-style addressing (http://<server>:9000/<bucket>) unless a Server URL with a host name is configured.

AWS CLI

aws configure set aws_access_key_id <access-key>
aws configure set aws_secret_access_key <secret-key>
aws s3 ls --endpoint-url http://<server-ip>:9000
aws s3 cp myfile.txt s3://my-bucket/ --endpoint-url http://<server-ip>:9000

rclone

[myznas]
type = s3
provider = Other
access_key_id = <access-key>
secret_access_key = <secret-key>
endpoint = http://<server-ip>:9000
force_path_style = true

curl (no extra tools)

curl --aws-sigv4 "aws:amz:us-east-1:s3" --user <access-key>:<secret-key> \
     -T myfile.txt http://<server-ip>:9000/my-bucket/myfile.txt

Troubleshooting

Problem Solution
Service does not start sudo journalctl -u rustfs; check the dataset is mounted and has free space
"configure the S3 server first" Open Configure and click Save & Apply once (also needed after moving from MinIO)
Access denied for a user Check the user is enabled and listed in the bucket's Users
TLS certificate errors Use https:// and trust (or skip verification of) the self-signed certificate
Install refused: checksum mismatch The download was altered or incomplete; try again. ZNAS never installs a file that does not match its pinned checksum

Clone this wiki locally