View a markdown version of this page

Virtual hosting of general purpose buckets - Amazon Simple Storage Service
Path-style requestsVirtual-hosted–style requestsHTTP Host header bucket specificationExamplesCustomizing Amazon S3 URLs with CNAME recordsHow to associate a hostname with an Amazon S3 bucketLimitationsBackward compatibility

Virtual hosting of general purpose buckets

Virtual hosting is the practice of serving multiple websites from a single web server. One way to differentiate sites in your Amazon S3 REST API requests is by using the apparent hostname of the Request-URI instead of just the path name part of the URI. An ordinary Amazon S3 REST request specifies a bucket by using the first slash-delimited component of the Request-URI path. Instead, you can use Amazon S3 virtual hosting to address a general purpose bucket in a REST API call by using the HTTP Host header. In practice, Amazon S3 interprets Host as meaning that most buckets are automatically accessible for limited types of requests at https://bucket-name.s3.region-code.amazonaws.com. For a complete list of Amazon S3 Regions and endpoints, see Amazon S3 endpoints and quotas in the Amazon Web Services General Reference.

Virtual hosting also has other benefits. By naming your bucket after your registered domain name and by making that name a DNS alias for Amazon S3, you can completely customize the URL of your Amazon S3 resources, for example, http://my.bucket-name.com/. You can also publish to the "root directory" of your bucket's virtual server. This ability can be important because many existing applications search for files in this standard location. For example, favicon.ico, robots.txt, and crossdomain.xml are all expected to be found at the root.

Important

When you're using virtual-hosted–style general purpose buckets with SSL, the SSL wildcard certificate matches only buckets that do not contain dots (.). To work around this limitation, use HTTP or write your own certificate-verification logic. For more information, see Amazon S3 Path Deprecation Plan on the AWS News Blog.

Path-style requests

Currently, Amazon S3 supports both virtual-hosted–style and path-style URL access in all AWS Regions. However, path-style URLs will be discontinued in the future. For more information, see the following Important note.

In Amazon S3, path-style URLs use the following format:

https://s3.region-code.amazonaws.com/bucket-name/key-name

For example, if you create a bucket named amzn-s3-demo-bucket1 in the US West (Oregon) Region, and you want to access the puppy.jpg object in that bucket, you can use the following path-style URL:

https://s3.us-west-2.amazonaws.com/amzn-s3-demo-bucket1/puppy.jpg
Important

Update (September 23, 2020) – To make sure that customers have the time that they need to transition to virtual-hosted–style URLs, we have decided to delay the deprecation of path-style URLs. For more information, see Amazon S3 Path Deprecation Plan – The Rest of the Story in the AWS News Blog.

Warning

When hosting website content that will be accessed from a web browser, avoid using path-style URLs, which might interfere with the browser same origin security model. To host website content, we recommend that you use either S3 website endpoints or a CloudFront distribution. For more information, see Website endpoints and Deploy a React-based single-page application to Amazon S3 and CloudFront in the AWS Perspective Guidance Patterns.

Virtual-hosted–style requests

In a virtual-hosted–style URI, the bucket name is part of the domain name in the URL.

Amazon S3 virtual-hosted–style URLs use the following format:

https://bucket-name.s3.region-code.amazonaws.com/key-name

In this example, amzn-s3-demo-bucket1 is the bucket name, US West (Oregon) is the Region, and puppy.png is the key name:

https://amzn-s3-demo-bucket1.s3.us-west-2.amazonaws.com/puppy.png

HTTP Host header bucket specification

As long as your GET request does not use the SSL endpoint, you can specify the bucket for the request by using the HTTP Host header. The Host header in a REST request is interpreted as follows:

  • If the Host header is omitted or its value is s3.region-code.amazonaws.com, the bucket for the request will be the first slash-delimited component of the Request-URI, and the key for the request will be the rest of the Request-URI. This is the ordinary method, as illustrated by the first and second examples in this section. Omitting the Host header is valid only for HTTP 1.0 requests.

  • Otherwise, if the value of the Host header ends in .s3.region-code.amazonaws.com, the bucket name is the leading component of the Host header's value up to .s3.region-code.amazonaws.com. The key for the request is the Request-URI. This interpretation exposes buckets as subdomains of .s3.region-code.amazonaws.com, as illustrated by the third and fourth examples in this section.

  • Otherwise, the bucket for the request is the lowercase value of the Host header, and the key for the request is the Request-URI. This interpretation is useful when you have registered the same DNS name as your bucket name and have configured that name to be a canonical name (CNAME) alias for Amazon S3. The procedure for registering domain names and configuring CNAME DNS records is beyond the scope of this guide, but the result is illustrated by the final example in this section.

Examples

This section provides example URLs and requests.

Example– Path-style URLs and requests

This example uses the following:

  • Bucket Name ‐ example.com

  • Region ‐ US East (N. Virginia)

  • Key Name ‐ homepage.html

The URL is as follows:

http://s3.us-east-1.amazonaws.com/example.com/homepage.html

The request is as follows:

GET /example.com/homepage.html HTTP/1.1
Host: s3.us-east-1.amazonaws.com

The request with HTTP 1.0 and omitting the Host header is as follows:

GET /example.com/homepage.html HTTP/1.0

For information about DNS-compatible names, see Limitations. For more information about keys, see Keys.

Example– Virtual-hosted–style URLs and requests

This example uses the following:

  • Bucket name ‐ amzn-s3-demo-bucket1

  • Region ‐ Europe (Ireland)

  • Key name ‐ homepage.html