Virtual Hosting of Buckets

Topics

Virtual Hosting, in general, is the practice of serving multiple web sites from a single web server. One way to differentiate sites is by using the apparent host name of the request instead of just the path name part of the URI. An ordinary Amazon S3 REST request specifies a bucket using the first slash delimited component of the Request-URI path. Alternatively, using Amazon S3 Virtual Hosting, you can address a bucket in a REST API call 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 http://bucketname.s3.amazonaws.com. Furthermore, 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.bucketname.com/

Besides the attractiveness of customized URLs, a second benefit of virtual hosting is the ability to publish to the 'root directory' of your bucket's virtual server. This can be important because many existing applications search for files in this standard location. For example, favicon.ico, robots.txt, crossdomain.xml, are all expected to be found at the root.

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 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.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 example in the following table. Note that omitting the Host header is only legal for HTTP 1.0 requests.
Otherwise, if the value of the Host header ends in '.s3.amazonaws.com', then the bucket name is the leading component of the Host header's value up to '.s3.amazonaws.com'. The key for the request is the Request-URI. This interpretation exposes buckets as sub-domains of s3.amazonaws.com, and is illustrated by the third and fourth example in the following table.
Otherwise, the bucket for the request will be the lower-cased 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 CNAME alias for Amazon S3. The procedure for registering domain names and configuring DNS is outside the scope of this document, but the result is illustrated by the final example in the following table.

Examples

This section provides example URLs and requests.

Example Path Style Method

This example uses johnsmith.net as the bucket name and homepage.html as the key name.

Following is the example URL.

http://s3.amazonaws.com/johnsmith/homepage.html

Following is the example request.

GET /johnsmith/homepage.html HTTP/1.1
Host: s3.amazonaws.com

Following is the example request with HTTP 1.0 omitting the host header.

GET /johnsmith/homepage.html
HTTP/1.0
Host: s3.amazonaws.com

EU bucket names must be DNS compatible and therefore do not support the path style method. Non-EU bucket names do not have to be DNS compatible and therefore can support the path style method. Non-EU buckets can be named, http://s3.amazonaws.com/[bucket-name]/[key], for example, http://s3.amazonaws.com/images.johnsmith.net/mydog.jpg.

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

Example Virtual Hosted Style Method

This example uses johnsmith.net as the bucket name and homepage.html as the key name.

Following is the example URL.

http://johnsmith.s3.amazonaws.com/homepage.html

Following is the example request.

GET /homepage.html HTTP/1.1
Host: johnsmith.s3.amazonaws.com

Following is the example request with the incorrect case. Notice that sentence case is irrelevant. However, uppercase buckets are not accessible using this method.

GET /homepage.html HTTP/1.1
Host: JohnSmith.s3.amazonaws.com

Example CNAME Method

This example uses www.johnsmith.net as the bucket name and homepage.html as the key name. To use this method, you must configure your DNS name as a CNAME alias for bucketname.s3.amazonaws.com.

Following is the example URL.

http://www.johnsmith.net/homepage.html

Following is the example request.

GET /homepage.html HTTP/1.1
Host: www.johnsmith.net

Customizing Amazon S3 URLs with CNAMEs

Depending on your needs, you might not want "s3.amazonaws.com" to appear on your web site or service. For example, if you host your web site's images on Amazon S3, you might prefer http://images.johnsmith.net/ as opposed to http://johnsmith-images.s3.amazonaws.com/.

Any bucket with a DNS compatible name may be referenced as follows: http://[BucketName].s3.amazonaws.com/[Filename], for example, http://images.johnsmith.net.s3.amazonaws.com/mydog.jpg. Using CNAME you can map images.johnsmith.net to an Amazon S3 host name so the previous URL could become: http://images.johnsmith.net/mydog.jpg.

The CNAME DNS record should alias your domain name to the appropriate virtual hosted style host name. For example, if your bucket name (and domain name) is images.johnsmith.net, the CNAME record should alias to images.johnsmith.net.s3.amazonaws.com.

images.johnsmith.net CNAME 			images.johnsmith.net.s3.amazonaws.com.

Setting the alias target to s3.amazonaws.com also works but may result in extra HTTP redirects.

	Note
	Amazon S3 only sees the original host name and is unaware of the CNAME mapping used to resolve the request.

To associate a host name with an Amazon S3 bucket using CNAMEs

Select a host name that belongs to a domain you control.
This example uses the images subdomain of the johnsmith.net domain.
Create a bucket that matches the host name.
In this example, the host and bucket names are images.johnsmith.net.
Note
Your bucket name must exactly match the host name.

Create a CNAME record that defines the host name as an alias for the Amazon S3 bucket. For example:

images.johnsmith.net CNAME images.johnsmith.net.s3.amazonaws.com

	Important
	For request routing reasons, the CNAME record must be defined exactly as shown in the preceding example. Otherwise, it might appear to operate correctly, but will eventually result in unpredictable behavior.

	Note
	The exact procedure for configuring DNS depends on your DNS server or DNS provider and is beyond scope of this document.

Limitations

Because DNS names are case insensitive, only lower-case buckets are addressable using the virtual hosting method. For more information, see Bucket Restrictions and Limitations.

Specifying the bucket for the request using the HTTP Host header is supported for non-SSL requests and when using the REST API. You cannot specify the bucket in SOAP by using a different endpoint.

Backward Compatibility

Early versions of Amazon S3 incorrectly ignored the HTTP Host header. Applications that depend on this undocumented behavior must be updated to set the Host header correctly. Because Amazon S3 determines the bucket name from Host when present, the most likely symptom of this problem is to receive an unexpected NoSuchBucket error result code.