Virtual Hosting of Buckets

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's interpretation of Host means 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.

Using the HTTP Host Header to Specify the Bucket

So long as your GET request does not use the SSL endpoint, you may 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 table below. 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 table below.
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 table below.

Examples

The following example illustrates these cases:

Example URL	Example Request	Bucket Name for Request	Key for Request	Notes
http://s3.amazonaws.com/ johnsmith/homepage.html	GET /johnsmith/homepage.html HTTP/1.1 Host: s3.amazonaws.com	johnsmith	homepage.html	The ordinary method
	GET /johnsmith/homepage.html HTTP/1.0	johnsmith	homepage.html	HTTP 1.0 may omit the Host header
http://johnsmith. s3.amazonaws.com/homepage.html	GET /homepage.html HTTP/1.1 Host: johnsmith.s3.amazonaws.com	johnsmith	homepage.html	All lower-case Amazon S3 buckets are automatically addressable by the sub-domain method.
	GET /homepage.html HTTP/1.1 Host: JohnSmith.s3.amazonaws.com	johnsmith	homepage.html	Note that the case of the Host header is insignificant. Upper-case bucket names are not accessible using this method.
http://www.johnsmith.net/ homepage.html	GET /homepage.html HTTP/1.1 Host: www.johnsmith.net	www.johnsmith.net	homepage.html	To host a website in Amazon S3 using this method, you must configure your DNS name as a CNAME alias for `bucketname`.s3.amazonaws.com.

Custom Amazon S3 URLs using 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 may prefer a URL like this:

http://images.johnsmith.net/

to one that looks like this:

http://johnsmith-images.s3.amazonaws.com/

To associate a hostname with an Amazon S3 bucket using CNAMEs

Select a hostname that belongs to a domain you control. This example uses the images subdomain of the johnsmith.net domain.
Create a bucket that matches the hostname. In this example, the hostname and bucket are named images.johnsmith.net.
Note
Your bucket name must exactly match the hostname.
Create a CNAME record that defines the hostname 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 above. 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.

	Note
Your bucket name must exactly match the hostname.

	Important
For request routing reasons, the CNAME record must be defined exactly as above. 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.

Specifying the bucket for the request using the HTTP Host header is supported:

For non-SSL requests.
Using the REST API. You cannot specify the bucket in SOAP by using a different endpoint.

Backwards 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.