S3 Setup Guide

Turn a ZFS dataset into S3-compatible object storage
OviOS Linux 6.2 Object Storage MinIO · ZFS
← Home ← Back to Docs

1 Overview

OviOS includes an S3-compatible object storage service built on MinIO. Buckets and objects are stored in a ZFS dataset you choose, so they get the same integrity, compression, snapshots and replication as the rest of your data. Any S3-aware application works with it: AWS SDKs, the AWS CLI, rclone, backup software and so on.

Item Value
S3 API https://<node-ip>:9000
Web console (optional) https://<node-ip>:9001
Credentials and data path /etc/ovios/s3/credentials (root only, mode 0600; holds the admin user, password and data path)
Certificates /etc/ovios/s3/certs/ (public.crt, private.key)
Data location /ovios/<pool>/<dataset>
Service name s3 (ovios-s3.service)
ℹ️

The S3 service is MinIO, distributed under the GNU AGPL v3.

2 Prerequisites

  • A pool that is imported and managed by OviOS. Pools created with pool create are managed automatically. Pools listed in options exclude.pools are not managed and cannot hold S3 data. A pool imported from another system is managed once it is marked: options exclude.pools reset marks every imported pool as managed (and clears all exclusions).
  • A dataset for the object data. Create a dedicated one so you can snapshot, size and replicate it independently, for example vol create tank/s3. vol create asks for a size, which is both the limit and a reservation for the bucket data.
  • A network address on the node that clients can reach (check with netsetup).
💡

Use a dataset on its own, not the root of a pool. Object stores grow, and a dedicated dataset lets you set quotas, compression and snapshot schedules just for S3.

3 Enabling S3

Enable the service with the options command. The first time you do this, OviOS runs a guided setup and asks three questions; the service starts once they are answered.

options s3.enable on

# Enter the volume path for S3 storage (e.g., pool/dataset): tank/s3
# Enter the S3 admin username: s3admin
# Enter the S3 admin password: ********
# Confirm the S3 admin password: ********
Prompt Notes
Volume path Enter pool/dataset. The dataset must exist, its pool must be imported, and the pool must be managed by OviOS. Data is stored under /ovios/pool/dataset.
Admin username Required. This is the S3 access key.
Admin password Asked twice, at least 8 characters. This is the S3 secret key.

OviOS writes the credentials to /etc/ovios/s3/credentials (mode 0600) and starts the service. If you cancel the setup (press Enter at the volume or username question) or an answer is rejected, nothing is started and s3.enable stays off. Check the service:

service s3 status
service             # then select → status-all to see S3 among all services
💡

On later boots the service starts automatically while s3.enable is on. If you enable S3 again later and the S3 dataset is missing or its pool is not imported, enabling is refused with a message naming the dataset, and s3.enable stays off.

4 Web Console

The web console lets you create buckets, manage access keys and browse objects from a browser. It is off by default, and it can only be switched on after S3 has been set up; until then the option is refused and stays off.

options s3.ui.enable on
service s3 restart   # apply the change

Browse to https://<node-ip>:9001 and sign in with the admin username and password you chose. To turn the console off again, use options s3.ui.enable off and restart the service.

5 Connecting Clients

Point any S3 client at https://<node-ip>:9000, use the admin username as the access key and the password as the secret key, and use path-style addressing.

AWS CLI

export AWS_ACCESS_KEY_ID=s3admin
export AWS_SECRET_ACCESS_KEY=your-password

aws --endpoint-url https://<node-ip>:9000 --no-verify-ssl s3 mb s3://backups
aws --endpoint-url https://<node-ip>:9000 --no-verify-ssl s3 cp file.tar s3://backups/
aws --endpoint-url https://<node-ip>:9000 --no-verify-ssl s3 ls s3://backups

rclone

# ~/.config/rclone/rclone.conf
[ovios]
type = s3
provider = Minio
access_key_id = s3admin
secret_access_key = your-password
endpoint = https://<node-ip>:9000
no_check_certificate = true
ℹ️

--no-verify-ssl and no_check_certificate are needed only while the node uses its default self-signed certificate. Install your own certificate (next section) and remove them.

6 Certificates

S3 is served over HTTPS. A self-signed certificate valid for ten years is generated when the S3 package is installed, in /etc/ovios/s3/certs/. To use a certificate issued by your own CA, replace the two files (keep them root-only, mode 0600) and restart the service:

cp your.crt /etc/ovios/s3/certs/public.crt
cp your.key /etc/ovios/s3/certs/private.key
chmod 600 /etc/ovios/s3/certs/public.crt /etc/ovios/s3/certs/private.key
service s3 restart

7 Managing the Service

service s3 status    # is it running?
service s3 restart   # apply credential or certificate changes
service s3 logs      # read the service log
options s3.enable off # stop and disable the service (data stays on the dataset)

Protecting the data

Because the objects live in a normal ZFS dataset, you can protect them like any other volume:

  • Take snapshots of the S3 dataset with snap.
  • Replicate it to another OviOS node with retadm.
  • The S3 settings (/etc/ovios/s3, including the credentials and certificates) are saved to your pools automatically with the rest of the node configuration, so a stateless node gets them back at boot. They are also in the web dashboard's Backup Config archive. Configuration sync to replication partners (sync-config sync) does not copy them; set S3 up on the partner separately.
💡

Turning S3 off does not delete anything. The dataset keeps all buckets and objects, and enabling S3 again with the same dataset serves them once more.

8 Troubleshooting

Message Cause and fix
Dataset '<name>' not found or pool is exported The dataset does not exist or its pool is not imported. Create the dataset, or import the pool (service zfs start, after options skip.import off if needed).
Pool '<name>' is not managed by OviOS The pool is excluded from OviOS management. Choose a dataset on a managed pool, or remove the restriction with options exclude.pools.
Password must be at least 8 characters Choose a longer admin password.
Passwords do not match The two password entries differ. Enter the same password twice.
MINIO_VOLUMES entry not found in credentials file The credentials file was edited and lost its data path. Run options s3.enable off, delete /etc/ovios/s3/credentials from the system shell (su-ovios) and enable S3 again to rerun the guided setup.
S3 service must be enabled before enabling the UI Run options s3.enable on and complete the guided setup first, then enable the console.
Clients report a certificate error The default certificate is self-signed. Trust it on the client, or install your own certificate (section 6).
Service does not start Run service s3 logs. Check that the S3 dataset is mounted and /etc/ovios/s3/credentials still contains the volume path.
OviOS Linux 6.2 — Storage made simple.