S3

RustFS exposes an S3-compatible REST API for common object-storage workloads. It supports AWS Signature Version 4 (SigV4) and works with AWS CLI, AWS SDKs, and other S3 clients when you configure the RustFS endpoint, region, credentials, and addressing style.

Overview

S3 organizes data into buckets and objects. With the default path-style addressing, a RustFS URL maps to storage as follows:

http://localhost:9000/my-bucket/path/to/hello.txt
                      | bucket | |---- object key ----|

RustFS covers the common S3 data plane used by applications, backup tools, and SDKs:

Authenticated clients sign requests with an access key and secret key. Anonymous requests are evaluated against the applicable bucket policy.

Configuration

The S3 API is enabled on the main RustFS listener. It does not require a separate protocol switch.

Use IAM users or service accounts instead of root credentials for applications, and grant only the required S3 actions.

Path-style addressing

Path-style addressing is the default and requires no DNS configuration. The bucket name is the first component of the request path:

http://localhost:9000/my-bucket/hello.txt

Configure clients with:

• Endpoint: http://localhost:9000
• Region: us-east-1
• Access key: <your-access-key>
• Secret key: <your-secret-key>
• Addressing style: path-style

Some clients default to virtual-hosted-style requests. Enable their path-style option, such as force_path_style=true in AWS SDK configuration or s3_use_path_style = true in Terraform.

Virtual-hosted-style addressing

Virtual-hosted-style addressing places the bucket name in the hostname. Set RUSTFS_SERVER_DOMAINS to each base domain that RustFS should recognize:

export RUSTFS_SERVER_DOMAINS="s3.example.com"

The same object is then addressed as:

https://my-bucket.s3.example.com/hello.txt

Configure wildcard DNS, such as *.s3.example.com, to resolve to the RustFS endpoint. For HTTPS, the certificate must also cover the bucket hostnames. Bucket names containing dots may require explicit certificate names because a single-label wildcard does not span multiple labels.

TLS and network access

For production, set RUSTFS_TLS_PATH to a directory containing rustfs_cert.pem and rustfs_key.pem, then use an https:// endpoint. Ensure clients trust the issuing certificate authority.

Allow the configured S3 API port through host firewalls and load balancers. The default is TCP port 9000; this listener also carries RustFS administrative and internode traffic, so do not expose it anonymously without appropriate network and IAM controls.

Usage

The following examples use AWS CLI with the canonical local endpoint. Install and configure AWS CLI before continuing.

Configure AWS CLI

aws configure

Enter these values when prompted:

AWS Access Key ID [None]: <your-access-key>
AWS Secret Access Key [None]: <your-secret-key>
Default region name [None]: us-east-1
Default output format [None]: json

Pass the RustFS endpoint to every command. The custom endpoint keeps these examples on RustFS instead of AWS S3.

export RUSTFS_ENDPOINT="http://localhost:9000"

Create and list buckets

aws --endpoint-url "$RUSTFS_ENDPOINT" s3api create-bucket \
	--bucket my-bucket

aws --endpoint-url "$RUSTFS_ENDPOINT" s3api list-buckets

Upload and list objects

printf 'Hello from RustFS\n' > hello.txt

aws --endpoint-url "$RUSTFS_ENDPOINT" s3 cp \
	hello.txt s3://my-bucket/path/to/hello.txt

aws --endpoint-url "$RUSTFS_ENDPOINT" s3 ls \
	s3://my-bucket/path/to/

AWS CLI automatically uses multipart upload when its transfer configuration selects it for a large object. RustFS supports the standard multipart create, upload-part, complete, list, and abort workflows.

Download and inspect an object

aws --endpoint-url "$RUSTFS_ENDPOINT" s3 cp \
	s3://my-bucket/path/to/hello.txt ./downloaded-hello.txt

aws --endpoint-url "$RUSTFS_ENDPOINT" s3api head-object \
	--bucket my-bucket \
	--key path/to/hello.txt

Create a presigned URL

Generate a time-limited URL that can download an object without exposing credentials:

aws --endpoint-url "$RUSTFS_ENDPOINT" s3 presign \
	s3://my-bucket/path/to/hello.txt \
	--expires-in 3600

The hostname, scheme, port, region, and object path used by the recipient must match the values used to sign the URL. Use the externally reachable endpoint when generating URLs for another machine.

Delete objects and buckets

aws --endpoint-url "$RUSTFS_ENDPOINT" s3 rm \
	s3://my-bucket/path/to/hello.txt

aws --endpoint-url "$RUSTFS_ENDPOINT" s3api delete-bucket \
	--bucket my-bucket

An S3 bucket must be empty before it can be deleted.

Known compatibility differences

Current RustFS compatibility tests cover the common workflows described above. The following areas are not equivalent to AWS S3 or MinIO:

• Bucket access logging and bucket ownership controls are planned rather than complete.
• ACL authorization is intentionally unsupported. Canned ACL headers have partial compatibility, while XML grant policies return NotImplemented. Prefer IAM and bucket policies.
• POST Object form uploads are implemented, but checksum handling for that workflow is not complete.
• Some multipart upload listing and part-lookup edge cases are outside the default compatibility gate.
• S3 Select currently accepts only uncompressed input.
• Access Point and Outposts copy-source forms are not implemented.
• MinIO administrative APIs are a separate compatibility surface and should not be inferred from S3 data-plane support.

Client behavior can also differ when a tool assumes AWS-specific services, storage classes, account ownership controls, or endpoint discovery. Always set the RustFS endpoint explicitly and test the exact operations your application uses.

Next steps

• Follow the complete AWS CLI example.
• Choose an S3 SDK for application integration.
• Configure credentials and access policies.
• Enable TLS before exposing the endpoint outside a trusted network.