Host prefix injection - Amazon SDKs and Tools
Examples of host prefix injectionSupport by Amazon SDKs and tools
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Host prefix injection

Note

For help in understanding the layout of settings pages, or in interpreting the Support by Amazon SDKs and tools table that follows, see Understanding the settings pages of this guide.

Host prefix injection is a feature where Amazon SDKs automatically prepend a prefix to the hostname of service endpoints for certain API operations. This prefix can be either a static string or a dynamic value that includes data from your request parameters.

For example, when using Amazon Simple Storage Service to perform actions on Amazon S3 objects or buckets, the SDK replaces your bucket name and Amazon Web Services account ID in the final API endpoint.

While this behavior is required for normal Amazon service endpoints, it can cause problems when using custom endpoints such as VPC endpoints or local testing tools. In these cases, you might need to disable host prefix injection.

Configure this functionality by using the following:

disable_host_prefix_injection - shared Amazon config file setting
AWS_DISABLE_HOST_PREFIX_INJECTION - environment variable
aws.disableHostPrefixInjection - JVM system property: Java/Kotlin only

This setting controls whether the SDK or tool will modify the endpoint hostname by prepending a host prefix as defined in your SDK's client object or variable.

Default value: false

Valid values:

  • true – Disable host prefix injection. The SDK will not modify the endpoint hostname.

  • false – Enable host prefix injection. The SDK will prepend the host prefix to the endpoint hostname.

Example of setting this value in the config file:

[default]
disable_host_prefix_injection = true

Linux/macOS example of setting environment variables via command line:

export AWS_DISABLE_HOST_PREFIX_INJECTION=true

Windows example of setting environment variables via command line:

setx AWS_DISABLE_HOST_PREFIX_INJECTION true

Examples of host prefix injection

The following table of examples show how SDKs modify the final endpoint when host prefix injection is enabled and disabled.

  • Host prefix: The template of the host prefix property string set on the SDK's client object or variable in code.

  • Inputs: Additional inputs set on the SDK's client object or variable in code.

  • Client endpoint: The client's derived endpoint.

  • Setting value: Resolved value for the previous setting.

  • Resulting endpoint: The resulting endpoint the SDK client uses to make the API call.

Host prefix Inputs Client endpoint Setting value Resulting endpoint
"data." {} "https://service.us-west-2.amazonaws.com" false "https://data.service.us-west-2.amazonaws.com"
"{Bucket}-{AccountId}." Bucket: "amzn-s3-demo-bucket1", AccountId:"123456789012" "https://service.us-west-2.amazonaws.com" false "https://amzn-s3-demo-bucket1-123456789012.service.us-west-2.amazonaws.com"
"data." {} "https://override.us-west-2.amazonaws.com" (as an override endpoint) true "https://override.us-west-2.amazonaws.com"

Support by Amazon SDKs and tools

The following SDKs support the features and settings described in this topic. Any partial exceptions are noted. Any JVM system property settings are supported by the Amazon SDK for Java and the Amazon SDK for Kotlin only.

SDK Supported Notes or more information
Amazon CLI v2 Yes
SDK for C++ No Setting not supported, but can be configured in code on the client using: enableHostPrefixInjection.
SDK for Go V2 (1.x) No Can be disabled using middleware.
SDK for Go 1.x (V1) No
SDK for Java 2.x No Setting not supported, but can be configured in code on the client using: SdkAdvancedClientOption.DISABLE_HOST_PREFIX_INJECTION.
SDK for Java 1.x No Setting not supported, but can be configured in code on the client using: withDisableHostPrefixInjection.
SDK for JavaScript 3.x No Setting not supported, but can be configured in code on the client using: disableHostPrefix.
SDK for JavaScript 2.x No Setting not supported, but can be configured in code on the client using: hostPrefixEnabled.
SDK for Kotlin No
SDK for .NET 4.x No Setting not supported, but can be configured in code on the client using: DisableHostPrefixInjection.
SDK for .NET 3.x No Setting not supported, but can be configured in code on the client using: DisableHostPrefixInjection.
SDK for PHP 3.x No Setting not supported, but can be configured in code on the client using: disable_host_prefix_injection.
SDK for Python (Boto3) Yes Can be configured in code on the client using: inject_host_prefix.
SDK for Ruby 3.x No Setting not supported, but can be configured in code on the client using: disable_host_prefix_injection.
SDK for Rust No
SDK for Swift No
Tools for PowerShell V5 No Setting not supported, but can be included in specific cmdlets using parameter -ClientConfig @{DisableHostPrefixInjection = $true}.
Tools for PowerShell V4 No Setting not supported, but can be included in specific cmdlets using parameter -ClientConfig @{DisableHostPrefixInjection = $true}.