AWS Documentation » Amazon Simple Storage Service (S3) » Developer Guide » Making Requests » Making Requests using the REST API » Virtual Hosting of Buckets	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

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.

Important

Amazon S3 supports virtual-hosted-style and path-style access in all Regions. The path-style syntax, however, requires that you use the region-specific endpoint when attempting to access a bucket. For example, if you have a bucket called mybucket that resides in the EU, you want to use path-style syntax, and the object is named puppy.jpg, the correct URI is http://s3-eu-west-1.amazonaws.com/mybucket/puppy.jpg. You will receive a “PermanentRedirect” error, an HTTP response code 301, and a message indicating what the correct URI is for your resource if you try to access a non US Standard bucket with path-style syntax using:

http://s3.amazonaws.com
A different Region endpoint than where the bucket resides, for example, http://s3-euwest-1.amazonaws.com and the bucket was created with the location constraint of Northern-California

Note

Amazon S3 routes any virtual hosted style requests to the US standard region by default. When you create a bucket, in any region, Amazon S3 updates DNS to re-route the request to the correct location which might take time. In the meantime, the default rule applies and your virtual-hosted style request goes to the US standard region and Amazon S3 redirects it with HTTP 307 redirect to the correct region. For more information, see Request Redirection and the REST API.

When using virtual hosted-style buckets with SSL, the SSL wild card certificate only matches buckets that do not contain periods. To work around this, use HTTP or write your own certificate verification logic.

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.net/homepage.html HTTP/1.1
Host: s3.amazonaws.com

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

GET /johnsmith.net/homepage.html HTTP/1.0

For 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.net.s3.amazonaws.com/homepage.html

Following is the example request.

GET /homepage.html HTTP/1.1
Host: johnsmith.net.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.net.s3.amazonaws.com

Example Virtual Hosted Style Method for a Non US Standard Bucket

This example uses johnsmith.eu as the name for a bucket in the EU (Ireland) region and homepage.html as the key name.

Following is the example URL.

http://johnsmith.eu.s3-eu-west-1.amazonaws.com/homepage.html

Following is the example request.

GET /homepage.html HTTP/1.1
Host: johnsmith.eu.s3-eu-west-1.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/.

The bucket name must be the same as the CNAME. So http://images.johnsmith.net/filename would be the same as http://images.johnsmith.net.s3.amazonaws.com/filename if a CNAME were created to map images.johnsmith.net to images.johnsmith.net.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.

Amazon S3 uses the host name to determine the bucket name. For example, assume that you have configured www.example.com as a CNAME for www.example.com.s3.amazonaws.com. When you access http://www.example.com, Amazon S3 receives a request similar to the following:

GET / HTTP/1.1
Host: www.example.com
Date: date
Authorization: signatureValue

Because Amazon S3 only sees the original host name www.example.com and is unaware of the CNAME mapping used to resolve the request, the CNAME and the bucket name must be the same.

Any Amazon S3 endpoint can be used in a CNAME, for example, s3-ap-southeast-1.amazonaws.com can be used in CNAMEs. For more information about endpoints, see Request Endpoints.

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.

Document Conventions	« Previous Next »
Terms of Use	Did this page help you? Yes \| No \| Tell us about it...