# Using Amazon S3 dual-stack endpoints
<a name="dual-stack-endpoints"></a>

Amazon S3 dual-stack endpoints support requests to S3 buckets over IPv6 and IPv4. This section describes how to use dual-stack endpoints.

**Topics**
+ [Amazon S3 dual-stack endpoints](#dual-stack-endpoints-description)
+ [Using dual-stack endpoints from the Amazon CLI](#dual-stack-endpoints-cli)
+ [Using dual-stack endpoints from the Amazon SDKs](#dual-stack-endpoints-sdks)
+ [Using dual-stack endpoints from the REST API](#dual-stack-endpoints-examples-rest-api)

## Amazon S3 dual-stack endpoints
<a name="dual-stack-endpoints-description"></a>

When you make a request to a dual-stack endpoint, the bucket URL resolves to an IPv6 or an IPv4 address. For more information about accessing a bucket over IPv6, see [Making requests to Amazon S3 over IPv6](ipv6-access.md).

When using the REST API, you directly access an Amazon S3 endpoint by using the endpoint name (URI). You can access an S3 bucket through a dual-stack endpoint by using a virtual hosted-style or a path-style endpoint name. Amazon S3 supports only regional dual-stack endpoint names, which means that you must specify the region as part of the name. 

Use the following naming conventions for the dual-stack virtual hosted-style and path-style endpoint names:
+ Virtual hosted-style dual-stack endpoint: 

   {{bucketname}}.s3.dualstack.{{aws-region}}.amazonaws.com

   
+ Path-style dual-stack endpoint: 

  s3.dualstack.{{aws-region}}.amazonaws.com/{{bucketname}}

For more information, about endpoint name style, see [Accessing and listing an Amazon S3 bucket ](https://docs.amazonaws.cn//AmazonS3/latest/userguide/access-bucket-intro.html). For a list of Amazon S3 endpoints, see [Regions and Endpoints](https://docs.amazonaws.cn/general/latest/gr/s3.html) in the *Amazon Web Services General Reference*. 

**Important**  
You can use transfer acceleration with dual-stack endpoints. For more information, see [Getting started with Amazon S3 Transfer Acceleration ](https://docs.amazonaws.cn//AmazonS3/latest/userguide/transfer-acceleration-getting-started.html).

**Note**  
The two types of Virtual Private Cloud (VPC) endpoints that access Amazon S3 (*Interface VPC endpoints* and *Gateway VPC endpoints*) now have dual-stack support. For more information about VPC endpoints for Amazon S3, see [Amazon PrivateLink for Amazon S3](https://docs.amazonaws.cn//AmazonS3/latest/userguide/privatelink-interface-endpoints.html).

When using the Amazon Command Line Interface (Amazon CLI) and Amazon SDKs, you can use a parameter or flag to change to a dual-stack endpoint. You can also specify the dual-stack endpoint directly as an override of the Amazon S3 endpoint in the config file. The following sections describe how to use dual-stack endpoints from the Amazon CLI and the Amazon SDKs.

## Using dual-stack endpoints from the Amazon CLI
<a name="dual-stack-endpoints-cli"></a>

This section provides examples of Amazon CLI commands used to make requests to a dual-stack endpoint. For instructions on setting up the Amazon CLI, see [Developing with Amazon S3 using the Amazon CLI](setup-aws-cli.md). 

You set the configuration value `use_dualstack_endpoint` to `true` in a profile in your Amazon Config file to direct all Amazon S3 requests made by the `s3` and `s3api` Amazon CLI commands to the dual-stack endpoint for the specified region. You specify the region in the config file or in a command using the `--region` option. 

When using dual-stack endpoints with the Amazon CLI, both `path` and `virtual` addressing styles are supported. The addressing style, set in the config file, controls if the bucket name is in the hostname or part of the URL. By default, the CLI will attempt to use virtual style where possible, but will fall back to path style if necessary. For more information, see [Amazon CLI Amazon S3 Configuration](https://docs.amazonaws.cn/cli/latest/topic/s3-config.html). 

You can also make configuration changes by using a command, as shown in the following example, which sets `use_dualstack_endpoint` to `true` and `addressing_style` to `virtual` in the default profile. 

```
$ aws configure set default.s3.use_dualstack_endpoint true
$ aws configure set default.s3.addressing_style virtual
```

If you want to use a dual-stack endpoint for specified Amazon CLI commands only (not all commands), you can use either of the following methods: 
+ You can use the dual-stack endpoint per command by setting the `--endpoint-url` parameter to `https://s3.dualstack.{{aws-region}}.amazonaws.com` or `http://s3.dualstack.{{aws-region}}.amazonaws.com` for any `s3` or `s3api` command. 

  ```
  $ aws s3api list-objects --bucket {{bucketname}} --endpoint-url https://s3.dualstack.{{aws-region}}.amazonaws.com
  ```
+ You can set up separate profiles in your Amazon Config file. For example, create one profile that sets `use_dualstack_endpoint` to `true` and a profile that does not set `use_dualstack_endpoint`. When you run a command, specify which profile you want to use, depending upon whether or not you want to use the dual-stack endpoint. 

**Note**  
When using the Amazon CLI you currently cannot use transfer acceleration with dual-stack endpoints. However, support for the Amazon CLI is coming soon. For more information, see [ Enabling and using S3 Transfer Acceleration](https://docs.amazonaws.cn//AmazonS3/latest/userguide/transfer-acceleration.html#transfer-acceleration-requirements). 

## Using dual-stack endpoints from the Amazon SDKs
<a name="dual-stack-endpoints-sdks"></a>

This section provides examples of how to access a dual-stack endpoint by using the Amazon SDKs. 

### Amazon SDK for Java dual-stack endpoint example
<a name="dual-stack-endpoints-examples-java"></a>

The following example shows how to enable dual-stack endpoints when creating an Amazon S3 client using the Amazon SDK for Java.

For instructions on creating and testing a working Java sample, see [Getting Started](https://docs.amazonaws.cn/sdk-for-java/v1/developer-guide/getting-started.html) in the Amazon SDK for Java Developer Guide.

```
import com.amazonaws.AmazonServiceException;
import com.amazonaws.SdkClientException;
import com.amazonaws.auth.profile.ProfileCredentialsProvider;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;

public class DualStackEndpoints {

    public static void main(String[] args) {
        Regions clientRegion = Regions.DEFAULT_REGION;
        String bucketName = "*** Bucket name ***";

        try {
            // Create an Amazon S3 client with dual-stack endpoints enabled.
            AmazonS3 s3Client = AmazonS3ClientBuilder.standard()
                    .withCredentials(new ProfileCredentialsProvider())
                    .withRegion(clientRegion)
                    .withDualstackEnabled(true)
                    .build();

            s3Client.listObjects(bucketName);
        } catch (AmazonServiceException e) {
            // The call was transmitted successfully, but Amazon S3 couldn't process
            // it, so it returned an error response.
            e.printStackTrace();
        } catch (SdkClientException e) {
            // Amazon S3 couldn't be contacted for a response, or the client
            // couldn't parse the response from Amazon S3.
            e.printStackTrace();
        }
    }
}
```

If you are using the Amazon SDK for Java on Windows, you might have to set the following Java virtual machine (JVM) property: 

```
java.net.preferIPv6Addresses=true
```

### Amazon .NET SDK dual-stack endpoint example
<a name="dual-stack-endpoints-examples-dotnet"></a>

When using the Amazon SDK for .NET you use the `AmazonS3Config` class to enable the use of a dual-stack endpoint as shown in the following example. 

```
using Amazon;
using Amazon.S3;
using Amazon.S3.Model;
using System;
using System.Threading.Tasks;

namespace Amazon.DocSamples.S3
{
    class DualStackEndpointTest
    {
        private const string bucketName = "*** bucket name ***";
        // Specify your bucket region (an example region is shown).
        private static readonly RegionEndpoint bucketRegion = RegionEndpoint.USWest2;
        private static IAmazonS3 client;

        public static void Main()
        {
            var config = new AmazonS3Config
            {
                UseDualstackEndpoint = true,
                RegionEndpoint = bucketRegion
            };
            client = new AmazonS3Client(config);
            Console.WriteLine("Listing objects stored in a bucket");
            ListingObjectsAsync().Wait();
        }

        private static async Task ListingObjectsAsync()
        {
            try
            {
                var request = new ListObjectsV2Request
                {
                    BucketName = bucketName,
                    MaxKeys = 10
                };
                ListObjectsV2Response response;
                do
                {
                    response = await client.ListObjectsV2Async(request);

                    // Process the response.
                    foreach (S3Object entry in response.S3Objects)
                    {
                        Console.WriteLine("key = {0} size = {1}",
                            entry.Key, entry.Size);
                    }
                    Console.WriteLine("Next Continuation Token: {0}", response.NextContinuationToken);
                    request.ContinuationToken = response.NextContinuationToken;
                } while (response.IsTruncated == true);
            }
            catch (AmazonS3Exception amazonS3Exception)
            {
                Console.WriteLine("An AmazonS3Exception was thrown. Exception: " + amazonS3Exception.ToString());
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception: " + e.ToString());
            }
        }
    }
}
```

For information about setting up and running the code examples, see [Getting Started with the Amazon SDK for .NET](https://docs.amazonaws.cn/sdk-for-net/latest/developer-guide/net-dg-setup.html) in the *Amazon SDK for .NET Developer Guide*. 

## Using dual-stack endpoints from the REST API
<a name="dual-stack-endpoints-examples-rest-api"></a>

For information about making requests to dual-stack endpoints by using the REST API, see [Making requests to dual-stack endpoints by using the REST API](RESTAPI.md#rest-api-dual-stack).