S3Proxy

July 30, 2026 · View on GitHub

S3Proxy implements the S3 API and proxies requests, enabling several use cases:

translation from S3 to Backblaze B2, EMC Atmos, Google Cloud, Microsoft Azure, and OpenStack Swift
testing without Amazon by using the local filesystem
extension via middlewares
embedding into Java applications

Usage with Docker

Docker Hub hosts a Docker image and has instructions on how to run it.

Usage with Kubernetes

Reference manifests show how to wire the Docker image into Kubernetes, including health probes, graceful shutdown, and Secret-based credentials. Helm users may prefer the third-party s3proxy-chart.

Usage without Docker

Users can download releases from GitHub. Developers can build the project by running mvn package which produces a binary at target/s3proxy. S3Proxy requires Java 17 or newer to run.

Configure S3Proxy via a properties file. An example using the local file system as the storage backend with anonymous access:

s3proxy.authorization=none
s3proxy.endpoint=http://127.0.0.1:8080
jclouds.provider=filesystem
jclouds.filesystem.basedir=/tmp/s3proxy

First create the filesystem basedir:

mkdir /tmp/s3proxy

Next run S3Proxy. Linux and Mac OS X users can run the executable jar:

chmod +x s3proxy
s3proxy --properties s3proxy.conf

Windows users must explicitly invoke java:

java -jar s3proxy --properties s3proxy.conf

Finally test by creating a bucket then listing all the buckets:

$ curl --request PUT http://localhost:8080/testbucket

$ curl http://localhost:8080/
<?xml version="1.0" ?><ListAllMyBucketsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/"><Owner><ID>75aa57f09aa0c8caeab4f8c24e99d10f8e7faeebf76c078efc7c6caea54ba06a</ID><DisplayName>CustomersName@amazon.com</DisplayName></Owner><Buckets><Bucket><Name>testbucket</Name><CreationDate>2015-08-05T22:16:24.000Z</CreationDate></Bucket></Buckets></ListAllMyBucketsResult>

Usage with Java

Maven Central hosts S3Proxy artifacts and the wiki has instructions on Java use.

Supported storage backends

atmos
aws-s3 (Amazon-only, alias for aws-s3-sdk)
aws-s3-sdk (S3-compatible backends via AWS SDK, recommended)
aws-s3-jclouds (Amazon-only via jclouds, deprecated)
azureblob (alias for azureblob-sdk)
azureblob-sdk (recommended)
azureblob-jclouds (Azure Blob via jclouds, deprecated)
b2
filesystem (on-disk storage, alias for filesystem-nio2)
filesystem-nio2 (on-disk storage, recommended)
filesystem-jclouds (on-disk storage via jclouds, deprecated)
google-cloud-storage (alias for google-cloud-storage-sdk)
google-cloud-storage-sdk (recommended)
google-cloud-storage-jclouds (Google Cloud Storage via jclouds, deprecated)
openstack-swift (OpenStack Swift via jclouds)
openstack-swift-sdk (OpenStack Swift via openstack4j, Keystone v3 only)
rackspace-cloudfiles-uk and rackspace-cloudfiles-us
s3 (non-Amazon, alias for aws-s3-sdk)
s3-jclouds (non-Amazon S3 via jclouds, deprecated)
sftp (SFTP storage via Apache MINA SSHD)
transient (in-memory storage, alias for transient-nio2)
transient-nio2 (in-memory storage, recommended)
transient-jclouds (in-memory storage via jclouds, deprecated)

See the wiki for examples of configurations.

Assigning buckets to backends

S3Proxy can be configured to assign buckets to different backends with the same credentials. The configuration in the properties file is as follows:

s3proxy.bucket-locator.1=bucket
s3proxy.bucket-locator.2=another-bucket

In addition to the explicit names, glob syntax can be used to configure many buckets for a given backend.

A bucket (or a glob) cannot be assigned to multiple backends.

Middlewares

S3Proxy can modify its behavior based on middlewares:

S3Proxy can listen on HTTPS by setting the secure-endpoint and configuring a keystore. You can read more about how configure S3Proxy for SSL Support in the dedicated wiki page with Docker, Kubernetes or simply Java.

Limitations

S3Proxy has broad compatibility with the S3 API, however, it does not support:

ACLs other than private and public-read, including the x-amz-grant-* headers and any grant naming a specific grantee
BitTorrent hosting
bucket inventory, analytics, and metrics configuration
bucket lifecycle configuration
bucket logging
bucket notification configuration
bucket policies
bucket policy status
bucket replication
conditional delete using If-Match, x-amz-if-match-size or x-amz-if-match-last-modified-time
CORS bucket operations like getting or setting the CORS configuration for a bucket. S3Proxy only supports a static configuration (see below).
hosting static websites
object lock, including legal hold and retention
object ownership controls
object server-side encryption
object tagging
object versioning, see #74
paginating ListParts with part-number-marker
POST upload policies, see #73
public access block
reading a single part of a multipart object with partNumber, unless the object has only one part
requester pays buckets
restoring archived objects
select object content
transfer acceleration
x-amz-expected-bucket-owner

S3Proxy emulates the following operations:

conditional PUT object when using If-Match or If-None-Match, unless the azureblob-sdk provider is used
copy multi-part objects, see #76
multi-part upload on the filesystem and transient backends, which store a stub object to carry the metadata
object and bucket owners, which are always the same synthetic user

Some limitations depend on the storage backend:

limitation	backends
no per-object ACLs, including public-read	`azureblob-sdk`, `openstack-swift-sdk`
ETag is not the object MD5	`azureblob-sdk`, `google-cloud-storage-sdk`
`Cache-Control` not preserved	`google-cloud-storage-sdk`, `openstack-swift-sdk`
`Content-Encoding` not preserved	`google-cloud-storage-sdk`
`Content-Language` not preserved	`openstack-swift-sdk`
`Expires` not preserved	`azureblob-sdk`
`max-keys=0` not honored	`azureblob-sdk`

S3Proxy has basic CORS preflight and actual request/response handling. It can be configured within the properties file (and corresponding ENV variables for Docker):

s3proxy.cors-allow-origins=https://example\.com https://.+\.example\.com https://example\.cloud
s3proxy.cors-allow-methods=GET PUT
s3proxy.cors-allow-headers=Accept Content-Type
s3proxy.cors-allow-credential=true

CORS cannot be configured per bucket. s3proxy.cors-allow-all=true will accept any origin and header. Actual CORS requests are supported for GET, PUT, POST, HEAD and DELETE methods.

The wiki collects compatibility notes for specific storage backends.

Support

References

Apache jclouds provides storage backend support for S3Proxy
Ceph s3-tests help maintain and improve compatibility with the S3 API
fake-s3, gofakes3, minio, S3 ninja, and s3rver provide functionality similar to S3Proxy when using the filesystem backend
GlacierProxy and SwiftProxy provide similar functionality for the Amazon Glacier and OpenStack Swift APIs
s3mock - Adobe's s3 mock implementation
s3proxy-chart - Helm chart for deploying S3Proxy
sbt-s3 runs S3Proxy via the Scala Build Tool
swift3 provides an S3 middleware for OpenStack Swift
Zenko provide similar multi-cloud functionality

License

Licensed under the Apache License, Version 2.0