Skip to content
Sign in

SDKs and tools

Every client below is in SwiftFS's compatibility test suites. Each needs three things: the endpoint, the region, and an access key. For SwiftFS Cloud the endpoint is https://s3.swiftfs.rw and the region us-east-1.

AWS CLI

Version 2. Pass the endpoint on each command, or save it in a profile:

Terminal
aws configure set aws_access_key_id SW… --profile swiftfs
aws configure set aws_secret_access_key … --profile swiftfs
aws configure set region us-east-1 --profile swiftfs
aws configure set endpoint_url "$S3_ENDPOINT" --profile swiftfs

aws --profile swiftfs s3 ls
aws --profile swiftfs s3 sync ./site s3://acme-site/

Tested: mb, cp (including multipart and ranged downloads), ls, sync, rm --recursive, rb, presign, and the s3api bucket policy, CORS and upload-part-copy commands.

JavaScript and TypeScript (AWS SDK v3)

JavaScript
import { S3Client, ListObjectsV2Command } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: process.env.S3_ENDPOINT,
  region: process.env.AWS_REGION,
  forcePathStyle: true,
  // credentials: from AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
});

const { Contents } = await s3.send(new ListObjectsV2Command({ Bucket: "acme-media", Prefix: "photos/" }));

@aws-sdk/s3-request-presigner for presigned URLs and @aws-sdk/lib-storage for multipart uploads work as with AWS. See browser uploads.

Go (AWS SDK v2)

Go
cfg, err := config.LoadDefaultConfig(ctx, config.WithRegion(os.Getenv("AWS_REGION")))
if err != nil {
	return err
}
client := s3.NewFromConfig(cfg, func(o *s3.Options) {
	o.BaseEndpoint = aws.String(os.Getenv("S3_ENDPOINT"))
	o.UsePathStyle = true
})

The SDK's default integrity checksums and trailing checksums are verified by SwiftFS. Virtual-hosted addressing (UsePathStyle = false) works where the operator has configured it.

minio-go

Go
client, err := minio.New("s3.example.com", &minio.Options{
	Creds:  credentials.NewStaticV4(accessKeyID, secretAccessKey, ""),
	Secure: true,
	Region: "us-east-1",
})

Pass the endpoint's host without https://.

rclone

Configuration
[swiftfs]
type = s3
provider = Other
endpoint = https://s3.example.com
region = us-east-1
access_key_id = SW…
secret_access_key = …
Terminal
rclone copy ./backups swiftfs:acme-backups
rclone check ./backups swiftfs:acme-backups   # compares sizes and hashes

s3cmd

Configuration
# ~/.s3cfg
access_key = SW…
secret_key = …
host_base = s3.example.com
host_bucket = s3.example.com
bucket_location = us-east-1
use_https = True

host_bucket set to the plain host makes s3cmd use path-style addresses.

Other clients

Tools and SDKs that let you set a custom S3 endpoint usually work, but only the ones above are in the test suite. Python's boto3, for one, needs endpoint_url and path-style addressing:

python
import boto3
from botocore.config import Config

s3 = boto3.client("s3", endpoint_url=S3_ENDPOINT, region_name="us-east-1",
                  config=Config(s3={"addressing_style": "path"}))

The compatibility matrix lists exactly what each tested client exercised.