Skip to content

Interface: S3-API

Configuration of LeoGateway

Update LeoGateway's protocol configuration to s3 in your LeoGateway configuration

1
2
3
4
5
## --------------------------------------------------------------------
## GATEWAY Protocol
## --------------------------------------------------------------------
## Gateway Protocol to use: [s3 | rest | embed | nfs]
protocol = s3

S3 API Implementation Status

Object Operation

No API Status
1 DELETE Object Yes
2 Delete Multiple Objects Yes
3 GET Object Yes
4 GET Object ACL Plans to support with v1.5
5 GET Object torrent No
6 HEAD Object Yes
7 POST Object Yes
8 PUT Object Yes
9 PUT Object ACL Plans to support with v1.5
10 PUT Object - Copy Yes
11 Initiate Multipart Upload Yes
12 Upload Part Yes
13 Upload Part - Copy Yes
14 Complete Multipart Upload Yes
15 Abort Multipart Upload Yes
16 List Parts No

Bucket Operation

No API Status
1 DELETE Bucket Yes
2 DELETE Bucket life cycle No
3 DELETE Bucket policy No
4 DELETE Bucket website No
5 GET Bucket (List Objects) Yes
6 GET Bucket ACL Yes
7 GET Bucket life cycle No
8 GET Bucket policy No
9 GET Bucket location Yes
10 GET Bucket logging No
11 GET Bucket notification No
12 GET Bucket Object versions Plan to support with v2.0
13 GET Bucket requestPayment No
14 GET Bucket versioning Plan to support with v2.0
15 GET Bucket website No
16 HEAD Bucket Yes
17 List Multipart Uploads No
18 PUT Bucket Yes
19 PUT Bucket ACL Yes
20 PUT Bucket life cycle No
21 PUT Bucket policy No
22 PUT Bucket logging No
23 PUT Bucket notification No
24 PUT Bucket requestPayment No
24 PUT Bucket versioning Plan to support with v2.0
25 PUT Bucket website No

Amazon S3 Interface

Amazon S3 Official Documentation

How to determine the name of Bucket

  • Virtual Hosting of Buckets
  • Values used for determining the name:
    • S3 uses a HTTP host header or a path segment in the HTTP request line
    • How S3 determines what to use depends on a domain name

1. https://s3.amazonaws.com/bucket/path_to_file

In this case, a bucket's name is the first segment of a path.

Name Value
Request line GET /bucket/path_to_file HTTP/1.1
Host header Host: s3.amazonaws.com

2. https://www.example.com.s3.amazonaws.com/path_to_file

In this case, the name of the bucket is the part of the domain name before .s3.amazonaws.com.

Name Value
Request line GET /path_to_file HTTP/1.1
Host header Host: www.example.com.s3.amazonaws.com

3. https://www.example.com/path_to_file

In this case, a bucket's name is equal to the FQDN.

Name Value
Request line GET /path_to_file HTTP/1.1
Host header Host header

The argument of LeoFS’ whereis OR purge commands should be "www.example.com/path_to_file".

Naming Rule of a Bucket

We recommend as a best practice that you always use DNS-compliant bucket names regardless of the region in which you create the bucket.

  • Bucket names can be as long as between 3 and 255 characters.
  • Bucket names can contain lowercase letters, numbers, periods (.), dashes (-) and underscores (_).
  • Bucket names must not be formatted as an IP address (e.g., 192.168.5.4).
  • Bucket name cannot start and end with periods (.), dashes (-) and underscores (_).

How to deal with Content-Type Request Header on PUT

Before 1.4.2, LeoFS had ignored Content-Type Request Header on PUT/POST and deduced the MIME type based on the file name extension and set that value to Content-Type Response Header on GET/HEAD. Since it turns out that this behaviour is different form AWS-S3 spec, we've decided to make it compatible with AWS-S3 spec while providing the old behaviour as well to ensure the backward compatibility for some users.

Since the old behaviour is set as default, if you want the new behaviour then you would have to set http.is_compatible_with_s3_content_type in leo_gateway.conf to true.

Before 1.4.2

For example, say you uploaded the file named path/to/file.jpg with Content-Type set to image/png then on GET you would download the file with Content-Type set to image/jpg in accordance with its extention.

Since 1.4.3

For example, say you uploaded the file named path/to/file.jpg with Content-Type set to image/png then on GET you would download the file with Content-Type set to image/png in accordance with Content-Type included in the request.

Keep using the old behaviour even after upgrading to 1.4.3 or higher ones

It's possible to do so by setting http.is_compatible_with_s3_content_type in leo_gateway.conf to false.

S3 Clients