# Configure the Instance Metadata Service options The Instance Metadata Service (IMDS) runs locally on every EC2 instance. The *instance metadata options* refer to a set of configurations that control the accessibility and behavior of the IMDS on an EC2 instance. You can configure the following instance metadata options on each instance: **Instance metadata service (IMDS)**: `enabled` \$1 `disabled` You can enable or disable the IMDS on an instance. When disabled, you or any code won't be able to access the instance metadata on the instance. The IMDS has two endpoints on an instance: IPv4 (`169.254.169.254`) and IPv6 (`[fd00:ec2::254]`). When you enable the IMDS, the IPv4 endpoint is automatically enabled. If you want to enable the IPv6 endpoint, you need to do so explicitly. **IMDS IPv6 endpoint**: `enabled` \$1 `disabled` You can explicitly enable the IPv6 IMDS endpoint on an instance. When the IPv6 endpoint is enabled, the IPv4 endpoint remains enabled. The IPv6 endpoint is only supported on [Nitro-based instances](instance-types.md#instance-hypervisor-type) in [IPv6-supported subnets](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-ip-address-range) (dual stack or IPv6 only). **Metadata version**: `IMDSv1 or IMDSv2 (token optional)` \$1 `IMDSv2 only (token required)` When requesting instance metadata, IMDSv2 calls require a token. IMDSv1 calls do not require a token. You can configure an instance to allow either IMDSv1 or IMDSv2 calls (where a token is optional), or to only allow IMDSv2 calls (where a token is required). **Metadata response hop limit**: `1`–`64` The hop limit is the number of network hops that the PUT response is allowed to make. You can set the hop limit to a minimum of `1` and a maximum of `64`. In a container environment, a hop limit of `1` can cause issues. For information about how to mitigate these issues, see the information about container environments under [Instance metadata access considerations](instancedata-data-retrieval.md#imds-considerations). **Access to tags in instance metadata**: `enabled` \$1 `disabled` You can enable or disable access to the instance's tags from an instance's metadata. For more information, see [View tags for your EC2 instances using instance metadata](work-with-tags-in-IMDS.md). To view an instance's current configuration, see [Query instance metadata options for existing instances](instancedata-data-retrieval.md#query-IMDS-existing-instances). ## Where to configure instance metadata options Instance metadata options can be configured at different levels, as follows: + **Account** – You can set default values for the instance metadata options at the account level for each AWS Region. When an instance is launched, the instance metadata options are automatically set to the account-level values. You can change these values at launch. Account-level default values do not affect existing instances. + **AMI** – You can set the `imds-support` parameter to `v2.0` when you register or modify an AMI. When an instance is launched with this AMI, the instance metadata version is automatically set to IMDSv2 and the hop limit is set to 2. + **Instance** – You can change all the instance metadata options on an instance at launch, overriding the default settings. You can also change the instance metadata options after launch on a running or stopped instance. Note that changes may be restricted by an IAM or SCP policy. For more information, see [Configure instance metadata options for new instances](configuring-IMDS-new-instances.md) and [Modify instance metadata options for existing instances](configuring-IMDS-existing-instances.md). ## Order of precedence for instance metadata options The value for each instance metadata option is determined at instance launch, following a hierarchical order of precedence. The hierarchy, with the highest precedence at the top, is as follows: + **Precedence 1: Instance configuration at launch** – Values can be specified either in the launch template or in the instance configuration. Any values specified here override values specified at the account level or in the AMI. + **Precedence 2: Account settings** – If a value is not specified at instance launch, then it is determined by the account-level settings (which are set for each AWS Region). Account-level settings either include a value for each metadata option, or indicate no preference at all. + **Precedence 3: AMI configuration** – If a value is not specified at instance launch or at the account level, then it is determined by the AMI configuration. This applies only to `HttpTokens` and `HttpPutResponseHopLimit`. Each metadata option is evaluated separately. The instance can be configured with a mix of direct instance configuration, account-level defaults, and the configuration from the AMI. You can change the value of any metadata option after launch on a running or stopped instance, unless changes are restricted by an IAM or SCP policy. **Note** The account-level IMDSv2 enforcement setting is evaluated after the order of precedence has determined the instance's IMDS settings. When IMDSv2 enforcement is enabled, instances enabled with IMDSv1 will fail. For more information about enforcement, see [Enforce IMDSv2 at the account level](configuring-IMDS-new-instances.md#enforce-imdsv2-at-the-account-level). **Warning** If IMDSv2 enforcement is enabled and `httpTokens` has not been set to `required` in either the instance configuration at launch, the account settings, or the AMI configuration, your launch will fail. **Example 1 – Determine values for metadata options** In this example, an EC2 instance is launched into a Region where the `HttpPutResponseHopLimit` is set to `1` at the account level. The specified AMI has `ImdsSupport` set to `v2.0`. No metadata options are specified directly on the instance at launch. The instance is launched with the following metadata options: ``` "MetadataOptions": { ... "HttpTokens": "required", "HttpPutResponseHopLimit": 1, ... ``` These values were determined as follows: + **No metadata options specified at launch:** During the launch of the instance, specific values for the metadata options were not provided either in the instance launch parameters or in the launch template. + **Account settings take next precedence:** In the absence of specific values specified at launch, the settings at the account level within the Region take precedence. This means that the default values configured at the account level are applied. In this case, the `HttpPutResponseHopLimit` was set to `1`. + **AMI settings take last precedence:** In the absence of a specific value specified at launch or at the account level for `HttpTokens` (the instance metadata version), the AMI setting is applied. In this case, the AMI setting `ImdsSupport: v2.0` determined that `HttpTokens` was set to `required`. Note that while the AMI setting `ImdsSupport: v2.0` is designed to set `HttpPutResponseHopLimit: 2`, it was overridden by the account-level setting `HttpPutResponseHopLimit: 1`, which has higher precedence. **Example 2 – Determine values for metadata options** In this example, the EC2 instance is launched with the same settings as in the previous Example 1, but with `HttpTokens` set to `optional` directly on the instance at launch. The instance is launched with the following metadata options: ``` "MetadataOptions": { ... "HttpTokens": "optional", "HttpPutResponseHopLimit": 1, ... ``` The value for `HttpPutResponseHopLimit` is determined in the same way as in Example 1. However, the value for `HttpTokens` is determined as follows: Metadata options configured on the instance at launch take first precedence. Even though the AMI was configured with `ImdsSupport: v2.0` (in other words, `HttpTokens` is set to `required`), the value specified on the instance at launch (`HttpTokens` set to `optional`) took precedence. **Example 3 – Determine values for metadata options with HttpTokensEnforced enabled** In this example, the account in the Region has `HttpTokens = required` and `HttpTokensEnforced = enabled`. Consider the following EC2 instance launch attempts: + Launch attempt with `HttpTokens` set to `optional` – The launch fails because the account-level enforcement is enabled (`HttpTokensEnforced = enabled`) and the launch parameter takes precedence over the account default. + Launch attempt with `HttpTokens` set to `required` – The launch succeeds because it complies with the account-level enforcement. + Launch attempt with no `HttpTokens` value specified – The launch succeeds because the value defaults to `required` based on the account settings. ### Set the instance metadata version When an instance is launched, the value for the instance *metadata version* is either **IMDSv1 or IMDSv2 (token optional)** (`httpTokens=optional`) or **IMDSv2 only (token required) (`httpTokens=required`) **. At instance launch, you can either manually specify the value for the metadata version, or use the default value. If you manually specify the value, it overrides any defaults. If you opt not to manually specify the value, it will be determined by a combination of default settings. The following flowchart shows how the metadata version for an instance at launch is determined by the settings at the different levels of the configuration and where enforcement is evaluated. The table that follows provides the specific settings at each level. ![\[A flowchart that shows the evaluation points for the instance metadata version and IMDSv2 enforcement.\]](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/images/imds-defaults-launch-flow.png) The table shows how the metadata version for an instance at launch (indicated by **Resulting instance configuration** in column 4) is determined by the settings at the different levels of configuration. The order of precedence is from left to right, where the first column takes the highest precedence, as follows: + Column 1: **Launch parameter** – Represents the setting on the instance that you manually specify at launch. + Column 2: **Account level default** – Represents the setting for the account. + Column 3: **AMI default** – Represents the setting on the AMI. | Launch parameter | Account level default | AMI default | Resulting instance configuration | | --- | --- | --- | --- | | V2 only (token required) | No preference | V2 only | V2 only | | V2 only (token required) | V2 only | V2 only | V2 only | | V2 only (token required) | V1 or V2 | V2 only | V2 only | | V1 or V2 (token optional) | No preference | V2 only | V1 or V2 | | V1 or V2 (token optional) | V2 only | V2 only | V1 or V2 | | V1 or V2 (token optional) | V1 or V2 | V2 only | V1 or V2 | | Not set | No preference | V2 only | V2 only | | Not set | V2 only | V2 only | V2 only | | Not set | V1 or V2 | V2 only | V1 or V2 | | V2 only (token required) | No preference | null | V2 only | | V2 only (token required) | V2 only | null | V2 only | | V2 only (token required) | V1 or V2 | null | V2 only | | V1 or V2 (token optional) | No preference | null | V1 or V2 | | V1 or V2 (token optional) | V2 only | null | V1 or V2 | | V1 or V2 (token optional) | V1 or V2 | null | V1 or V2 | | Not set | No preference | null | V1 or V2 | | Not set | V2 only | null | V2 only | | Not set | V1 or V2 | null | V1 or V2 | ## Use IAM condition keys to restrict instance metadata options You can use IAM condition keys in an IAM policy or SCP as follows: + Allow an instance to launch only if it's configured to require the use of IMDSv2 + Restrict the number of allowed hops + Turn off access to instance metadata **Topics** + [ ## Where to configure instance metadata options ](#where-to-configure-instance-metadata-options) + [ ## Order of precedence for instance metadata options ](#instance-metadata-options-order-of-precedence) + [ ## Use IAM condition keys to restrict instance metadata options ](#iam-condition-keys-and-imds) + [ # Configure instance metadata options for new instances ](configuring-IMDS-new-instances.md) + [ # Modify instance metadata options for existing instances ](configuring-IMDS-existing-instances.md) **Note** You should proceed cautiously and conduct careful testing before making any changes. Take note of the following: If you enforce the use of IMDSv2, applications or agents that use IMDSv1 for instance metadata access will break. If you turn off all access to instance metadata, applications or agents that rely on instance metadata access to function will break. For IMDSv2, you must use `/latest/api/token` when retrieving the token. (Windows only) If your PowerShell version is earlier than 4.0, you must [update to Windows Management Framework 4.0](https://devblogs.microsoft.com/powershell/windows-management-framework-wmf-4-0-update-now-available-for-windows-server-2012-windows-server-2008-r2-sp1-and-windows-7-sp1/) to require the use of IMDSv2. # Configure instance metadata options for new instances You can configure the following instance metadata options for new instances. **Topics** + [ ## Require the use of IMDSv2 ](#configure-IMDS-new-instances) + [ ## Enable the IMDS IPv4 and IPv6 endpoints ](#configure-IMDS-new-instances-ipv4-ipv6-endpoints) + [ ## Turn off access to instance metadata ](#configure-IMDS-new-instances--turn-off-instance-metadata) + [ ## Allow access to tags in instance metadata ](#configure-IMDS-new-instances-tags-in-instance-metadata) **Note** The settings for these options are configured at the account level, either directly in the account or by using a declarative policy. They must be configured in each AWS Region where you want to configure instance metadata options. Using a declarative policy allows you to apply the settings across multiple Regions simultaneously, as well as across multiple accounts simultaneously. When a declarative policy is in use, you can't modify the settings directly within an account. This topic describes how to configure the settings directly within an account. For information about using declarative policies, see [Declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html) in the *AWS Organizations User Guide.* ## Require the use of IMDSv2 You can use the following methods to require the use of IMDSv2 on your new instances. **Topics** + [ ### Set IMDSv2 as the default for the account ](#set-imdsv2-account-defaults) + [ ### Enforce IMDSv2 at the account level ](#enforce-imdsv2-at-the-account-level) + [ ### Configure the instance at launch ](#configure-IMDS-new-instances-instance-settings) + [ ### Configure the AMI ](#configure-IMDS-new-instances-ami-configuration) + [ ### Use an IAM policy ](#configure-IMDS-new-instances-iam-policy) ### Set IMDSv2 as the default for the account You can set the default version for the instance metadata service (IMDS) at the account level for each AWS Region. This means that when you launch a *new* instance, the instance metadata version is automatically set to the account-level default. However, you can manually override the value at launch or after launch. For more information about how the account-level settings and manual overrides affect an instance, see [Order of precedence for instance metadata options](configuring-instance-metadata-options.md#instance-metadata-options-order-of-precedence). **Note** Setting the account-level default does not reset *existing* instances. For example, if you set the account-level default to IMDSv2, any existing instances that are set to IMDSv1 are not affected. If you want to change the value on existing instances, you must manually change the value on the instances themselves. You can set the account default for the instance metadata version to IMDSv2 so that all *new* instances in the account launch with IMDSv2 required, and IMDSv1 will be disabled. With this account default, when you launch an instance, the following are the default values for the instance: + Console: **Metadata version** is set to **V2 only (token required)** and **Metadata response hop limit** is set to **2**. + AWS CLI: `HttpTokens` is set to `required` and `HttpPutResponseHopLimit` is set to `2`. **Note** Before setting the account default to IMDSv2, ensure that your instances do not depend on IMDSv1. For more information, see [Recommended path to requiring IMDSv2](instance-metadata-transition-to-version-2.md#recommended-path-for-requiring-imdsv2). ------ #### [ Console ] **To set IMDSv2 as the default for the account for the specified Region** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. To change the AWS Region, use the Region selector in the upper-right corner of the page. 1. In the navigation pane, choose **Dashboard**. 1. On the **Account attributes** card, under **Settings**, choose **Data protection and security**. 1. Next to **IMDS defaults**, choose **Manage**. 1. On the **Manage IMDS defaults** page, do the following: 1. For **Instance metadata service**, choose **Enabled**. 1. For **Metadata version**, choose **V2 only (token required)**. 1. For **Metadata response hop limit**, specify **2** if your instances will host containers. Otherwise, select **No preference**. When no preference is specified, at launch, the value defaults to **2** if the AMI has the setting `ImdsSupport: v2.0`; otherwise it defaults to **1**. 1. Choose **Update**. ------ #### [ AWS CLI ] **To set IMDSv2 as the default for the account for the specified Region** Use the [modify-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-defaults.html) command and specify the Region in which to modify the IMDS account level settings. Include `--http-tokens` set to `required` and `--http-put-response-hop-limit` set to `2` if your instances will host containers. Otherwise, specify `-1` to indicate no preference. When `-1` (no preference) is specified, at launch, the value defaults to `2` if the AMI has the setting `ImdsSupport: v2.0`; otherwise it defaults to `1`. ``` aws ec2 modify-instance-metadata-defaults \ --region us-east-1 \ --http-tokens required \ --http-put-response-hop-limit 2 ``` The following is example output. ``` { "Return": true } ``` **To view the default account settings for the instance metadata options for the specified Region** Use the [get-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/get-instance-metadata-defaults.html) command and specify the Region. ``` aws ec2 get-instance-metadata-defaults --region us-east-1 ``` The following is example output. ``` { "AccountLevel": { "HttpTokens": "required", "HttpPutResponseHopLimit": 2 }, "ManagedBy": "account" } ``` The `ManagedBy` field indicates the entity that configured the settings. In this example, `account` indicates that the settings were configured directly in the account. A value of `declarative-policy` would mean the settings were configured by a declarative policy. For more information, see [Declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html) in the *AWS Organizations User Guide*. **To set IMDSv2 as the default for the account for all Regions** Use the [modify-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-defaults.html) command to modify the IMDS account level settings for all Regions. Include `--http-tokens` set to `required` and `--http-put-response-hop-limit` set to `2` if your instances will host containers. Otherwise, specify `-1` to indicate no preference. When `-1` (no preference) is specified, at launch, the value defaults to `2` if the AMI has the setting `ImdsSupport: v2.0`; otherwise it defaults to `1`. ``` echo -e "Region \t Modified" ; \ echo -e "-------------- \t ---------" ; \ for region in $( aws ec2 describe-regions \ --region us-east-1 \ --query "Regions[*].[RegionName]" \ --output text ); do (output=$( aws ec2 modify-instance-metadata-defaults \ --region $region \ --http-tokens required \ --http-put-response-hop-limit 2 \ --output text) echo -e "$region \t $output" ); done ``` The following is example output. ``` Region Modified -------------- --------- ap-south-1 True eu-north-1 True eu-west-3 True ... ``` **To view the default account settings for the instance metadata options for all Regions** Use the [get-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/get-instance-metadata-defaults.html) command. ``` echo -e "Region \t Level Hops HttpTokens" ; \ echo -e "-------------- \t ------------ ---- ----------" ; \ for region in $( aws ec2 describe-regions \ --region us-east-1 \ --query "Regions[*].[RegionName]" \ --output text ); do (output=$( aws ec2 get-instance-metadata-defaults \ --region $region \ --output text) echo -e "$region \t $output" ); done ``` The following is example output. ``` Region Level Hops HttpTokens -------------- ------------ ---- ---------- ap-south-1 ACCOUNTLEVEL 2 required eu-north-1 ACCOUNTLEVEL 2 required eu-west-3 ACCOUNTLEVEL 2 required ... ``` ------ #### [ PowerShell ] **To set IMDSv2 as the default for the account for the specified Region** Use the [Edit-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataDefault.html) cmdlet and specify the Region in which to modify the IMDS account level settings. Include `-HttpToken` set to `required` and `-HttpPutResponseHopLimit` set to `2` if your instances will host containers. Otherwise, specify `-1` to indicate no preference. When `-1` (no preference) is specified, at launch, the value defaults to `2` if the AMI has the setting `ImdsSupport: v2.0`; otherwise it defaults to `1`. ``` Edit-EC2InstanceMetadataDefault ` -Region us-east-1 ` -HttpToken required ` -HttpPutResponseHopLimit 2 ``` The following is example output. ``` True ``` **To view the default account settings for the instance metadata options for the specified Region** Use the [Get-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceMetadataDefault.html) cmdlet and specify the Region. ``` Get-EC2InstanceMetadataDefault -Region us-east-1 | Format-List ``` The following is example output. ``` HttpEndpoint : HttpPutResponseHopLimit : 2 HttpTokens : required InstanceMetadataTags : ``` **To set IMDSv2 as the default for the account for all Regions** Use the [Edit-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataDefault.html) cmdlet to modify the IMDS account level settings for all Regions. Include `-HttpToken` set to `required` and `-HttpPutResponseHopLimit` set to `2` if your instances will host containers. Otherwise, specify `-1` to indicate no preference. When `-1` (no preference) is specified, at launch, the value defaults to `2` if the AMI has the setting `ImdsSupport: v2.0`; otherwise it defaults to `1`. ``` (Get-EC2Region).RegionName | ` ForEach-Object { [PSCustomObject]@{ Region = $_ Modified = (Edit-EC2InstanceMetadataDefault ` -Region $_ ` -HttpToken required ` -HttpPutResponseHopLimit 2) } } | ` Format-Table Region, Modified -AutoSize ``` Expected output ``` Region Modified ------ -------- ap-south-1 True eu-north-1 True eu-west-3 True ... ``` **To view the default account settings for the instance metadata options for all Regions** Use the [Get-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceMetadataDefault.html) cmdlet. ``` (Get-EC2Region).RegionName | ` ForEach-Object { [PSCustomObject]@{ Region = $_ HttpPutResponseHopLimit = (Get-EC2InstanceMetadataDefault -Region $_).HttpPutResponseHopLimit HttpTokens = (Get-EC2InstanceMetadataDefault -Region $_).HttpTokens } } | ` Format-Table -AutoSize ``` Example output ``` Region HttpPutResponseHopLimit HttpTokens ------ ----------------------- ---------- ap-south-1 2 required eu-north-1 2 required eu-west-3 2 required ... ``` ------ ### Enforce IMDSv2 at the account level You can enforce the use of IMDSv2 at the account level for each AWS Region. When enforced, instances can only launch if they're configured to require IMDSv2. This enforcement applies regardless of how the instance or AMI is configured. **Note** Before enabling IMDSv2 enforcement at the account level, ensure that your applications and AMIs support IMDSv2. For more information, see [Recommended path to requiring IMDSv2](instance-metadata-transition-to-version-2.md#recommended-path-for-requiring-imdsv2). If IMDSv2 enforcement is enabled and `httpTokens` is not set to `required` in either the instance configuration at launch, the account settings, or the AMI configuration, the instance launch will fail. For troubleshooting information, see [Launching an IMDSv1-enabled instance fails](troubleshooting-launch.md#launching-an-imdsv1-enabled-instance-fails). **Note** This setting does not change the IMDS version of existing instances, but blocks enabling IMDSv1 on existing instances that currently have IMDSv1 disabled. ------ #### [ Console ] **To enforce IMDSv2 for the account in the specified Region** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. To change the AWS Region, use the Region selector in the top right corner of the page. 1. In the navigation pane, choose **Dashboard**. 1. On the **Account attributes** card, under **Settings**, choose **Data protection and security**. 1. Next to **IMDS defaults**, choose **Manage**. 1. On the **Manage IMDS defaults** page, do the following: 1. For **Metadata version**, choose **V2 only (token required)**. 1. For **Enforce IMDSv2**, choose **Enabled**. 1. Choose **Update**. ------ #### [ AWS CLI ] **To enforce IMDSv2 for the account in the specified Region** Use the [modify-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-defaults.html) command and specify the Region in which to enforce IMDSv2. ``` aws ec2 modify-instance-metadata-defaults \ --region us-east-1 \ --http-tokens required \ --http-tokens-enforced enabled ``` The following is example output. ``` { "Return": true } ``` **To view the IMDSv2 enforcement setting for the account in a specific Region** Use the [get-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/get-instance-metadata-defaults.html) command and specify the Region. ``` aws ec2 get-instance-metadata-defaults --region us-east-1 ``` The following is example output. ``` { "AccountLevel": { "HttpTokens": "required", "HttpTokensEnforced": "enabled" }, "ManagedBy": "account" } ``` The `ManagedBy` field indicates the entity that configured the settings. In this example, `account` indicates that the settings were configured directly in the account. A value of `declarative-policy` would mean the settings were configured by a declarative policy. For more information, see [Declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html) in the *AWS Organizations User Guide*. **To enforce IMDSv2 for the account for all Regions** Use the [modify-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-defaults.html) command to enforce IMDSv2 in all Regions. ``` echo -e "Region \t Modified" ; \ echo -e "-------------- \t ---------" ; \ for region in $( aws ec2 describe-regions \ --region us-east-1 \ --query "Regions[*].[RegionName]" \ --output text ); do (output=$( aws ec2 modify-instance-metadata-defaults \ --region $region \ --http-tokens-enforced enabled \ --output text) echo -e "$region \t $output" ); done ``` The following is example output. ``` Region Modified -------------- --------- ap-south-1 True eu-north-1 True eu-west-3 True ... ``` **To view the IMDSv2 enforcement settings for the account in all Regions** Use the [get-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/get-instance-metadata-defaults.html) command. ``` echo -e "Region \t Level HttpTokensEnforced" ; \ echo -e "-------------- \t ------------ ----------------" ; \ for region in $( aws ec2 describe-regions \ --region us-east-1 \ --query "Regions[*].[RegionName]" \ --output text ); do (output=$( aws ec2 get-instance-metadata-defaults \ --region $region \ --query 'AccountLevel.HttpTokensEnforced' \ --output text) echo -e "$region \t ACCOUNTLEVEL $output" ); done ``` The following is example output. ``` Region Level HttpTokensEnforced -------------- ------------ ------------------ ap-south-1 ACCOUNTLEVEL enabled eu-north-1 ACCOUNTLEVEL enabled eu-west-3 ACCOUNTLEVEL enabled ... ``` ------ #### [ PowerShell ] **To enforce IMDSv2 for the account in the specified Region** Use the [Edit-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataDefault.html) cmdlet and specify the Region in which to enforce IMDSv2. ``` Edit-EC2InstanceMetadataDefault ` -Region us-east-1 ` -HttpToken required ` -HttpPutResponseHopLimit 2 ``` The following is example output. ``` @{ Return = $true } ``` **To view the IMDSv2 enforcement setting for the account in a specific Region** Use the Get-EC2InstanceMetadataDefault command and specify the Region. ``` Get-EC2InstanceMetadataDefault -Region us-east-1 ``` The following is example output. ``` @{ AccountLevel = @{ HttpTokens = "required" HttpTokensEnforced = "enabled" } ManagedBy = "account" } ``` The `ManagedBy` field indicates the entity that configured the settings. In this example, `account` indicates that the settings were configured directly in the account. A value of `declarative-policy` would mean the settings were configured by a declarative policy. For more information, see [Declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html) in the *AWS Organizations User Guide*. **To enforce IMDSv2 for the account for all Regions** Use the [modify-instance-metadata-defaults](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-defaults.html) command to enforce IMDSv2 in all Regions. ``` echo -e "Region \t Modified" ; \ echo -e "-------------- \t ---------" ; \ for region in $( aws ec2 describe-regions \ --region us-east-1 \ --query "Regions[*].[RegionName]" \ --output text ); do (output=$( aws ec2 modify-instance-metadata-defaults \ --region $region \ --http-tokens-enforced enabled \ --output text) echo -e "$region \t $output" ); done ``` The following is example output. ``` Region Modified -------------- --------- ap-south-1 True eu-north-1 True eu-west-3 True ... ``` **To set IMDSv2 as the default for the account for all Regions** Use the [Edit-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataDefault.html) cmdlet to modify the IMDS account level settings for all Regions. Include `-HttpToken` set to `required` and `-HttpPutResponseHopLimit` set to `2` if your instances will host containers. Otherwise, specify `-1` to indicate no preference. When `-1` (no preference) is specified, at launch, the value defaults to `2` if the AMI has the setting `ImdsSupport: v2.0`; otherwise it defaults to `1`. ``` (Get-EC2Region).RegionName | ` ForEach-Object { [PSCustomObject]@{ Region = $_ Modified = (Edit-EC2InstanceMetadataDefault ` -Region $_ ` -HttpToken required ` -HttpPutResponseHopLimit 2) } } | ` Format-Table Region, Modified -AutoSize ``` Expected output ``` Region Modified ------ -------- ap-south-1 True eu-north-1 True eu-west-3 True ... ``` **To view the default account settings for the instance metadata options for all Regions** Use the [Get-EC2InstanceMetadataDefault](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-EC2InstanceMetadataDefault.html) cmdlet. ``` (Get-EC2Region).RegionName | ` ForEach-Object { [PSCustomObject]@{ Region = $_ HttpPutResponseHopLimit = (Get-EC2InstanceMetadataDefault -Region $_).HttpPutResponseHopLimit HttpTokens = (Get-EC2InstanceMetadataDefault -Region $_).HttpTokens } } | ` Format-Table -AutoSize ``` Example output ``` Region HttpPutResponseHopLimit HttpTokens ------ ----------------------- ---------- ap-south-1 2 required eu-north-1 2 required eu-west-3 2 required ... ``` ------ ### Configure the instance at launch When you [launch an instance](ec2-launch-instance-wizard.md), you can configure the instance to require the use of IMDSv2 by configuring the following fields: + Amazon EC2 console: Set **Metadata version** to **V2 only (token required)**. + AWS CLI: Set `HttpTokens` to `required`. When you specify that IMDSv2 is required, you must also enable the Instance Metadata Service (IMDS) endpoint by setting **Metadata accessible** to **Enabled** (console) or `HttpEndpoint` to `enabled` (AWS CLI). In a container environment, when IMDSv2 is required, we recommend setting the hop limit to `2`. For more information, see [Instance metadata access considerations](instancedata-data-retrieval.md#imds-considerations). ------ #### [ Console ] **To require the use of IMDSv2 on a new instance** + When launching a new instance in the Amazon EC2 console, expand **Advanced details**, and do the following: + For **Metadata accessible**, choose **Enabled**. + For **Metadata version**, choose **V2 only (token required)**. + (Container environment) For **Metadata response hop limit**, choose **2**. For more information, see [Advanced details](ec2-instance-launch-parameters.md#liw-advanced-details). ------ #### [ AWS CLI ] **To require the use of IMDSv2 on a new instance** The following [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) example launches a `c6i.large` instance with `--metadata-options` set to `HttpTokens=required`. When you specify a value for `HttpTokens`, you must also set `HttpEndpoint` to `enabled`. Because the secure token header is set to `required` for metadata retrieval requests, this requires the instance to use IMDSv2 when requesting instance metadata. In a container environment, when IMDSv2 is required, we recommend setting the hop limit to `2` with `HttpPutResponseHopLimit=2`. ``` aws ec2 run-instances \ --image-id ami-0abcdef1234567890 \ --instance-type c6i.large \ ... --metadata-options "HttpEndpoint=enabled,HttpTokens=required,HttpPutResponseHopLimit=2" ``` ------ #### [ PowerShell ] **To require the use of IMDSv2 on a new instance** The following [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html) cmdlet example launches a `c6i.large` instance with `MetadataOptions_HttpEndpoint` set to `enabled` and the `MetadataOptions_HttpTokens` parameter to `required`. When you specify a value for `HttpTokens`, you must also set `HttpEndpoint` to `enabled`. Because the secure token header is set to `required` for metadata retrieval requests, this requires the instance to use IMDSv2 when requesting instance metadata. ``` New-EC2Instance ` -ImageId ami-0abcdef1234567890 ` -InstanceType c6i.large ` -MetadataOptions_HttpEndpoint enabled ` -MetadataOptions_HttpTokens required ``` ------ #### [ CloudFormation ] To specify the metadata options for an instance using CloudFormation, see the [AWS::EC2::LaunchTemplate MetadataOptions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-launchtemplate-metadataoptions.html) property in the *AWS CloudFormation User Guide*. ------ ### Configure the AMI When you register a new AMI or modify an existing AMI, you can set the `imds-support` parameter to `v2.0`. Instances launched from this AMI will have **Metadata version** set to **V2 only (token required)** (console) or `HttpTokens` set to `required` (AWS CLI). With these settings, the instance requires that IMDSv2 is used when requesting instance metadata. Note that when you set `imds-support` to `v2.0`, instances launched from this AMI will also have **Metadata response hop limit** (console) or `http-put-response-hop-limit` (AWS CLI) set to **2**. **Important** Do not use this parameter unless your AMI software supports IMDSv2. After you set the value to `v2.0`, you can't undo it. The only way to "reset" your AMI is to create a new AMI from the underlying snapshot. **To configure a new AMI for IMDSv2** Use one of the following methods to configure a new AMI for IMDSv2. ------ #### [ AWS CLI ] The following [register-image](https://docs.aws.amazon.com/cli/latest/reference/ec2/register-image.html) example registers an AMI using the specified snapshot of an EBS root volume as device `/dev/xvda`. Specify `v2.0` for the `imds-support` parameter so that instances launched from this AMI will require that IMDSv2 is used when requesting instance metadata. ``` aws ec2 register-image \ --name my-image \ --root-device-name /dev/xvda \ --block-device-mappings DeviceName=/dev/xvda,Ebs={SnapshotId=snap-0123456789example} \ --architecture x86_64 \ --imds-support v2.0 ``` ------ #### [ PowerShell ] The following [Register-EC2Image](https://docs.aws.amazon.com/powershell/latest/reference/items/Register-EC2Image.html) cmdlet example registers an AMI using the specified snapshot of an EBS root volume as device `/dev/xvda`. Specify `v2.0` for the `ImdsSupport` parameter so that instances launched from this AMI will require that IMDSv2 is used when requesting instance metadata. ``` Register-EC2Image ` -Name 'my-image' ` -RootDeviceName /dev/xvda ` -BlockDeviceMapping ( New-Object ` -TypeName Amazon.EC2.Model.BlockDeviceMapping ` -Property @{ DeviceName = '/dev/xvda'; EBS = (New-Object -TypeName Amazon.EC2.Model.EbsBlockDevice -Property @{ SnapshotId = 'snap-0123456789example' VolumeType = 'gp3' } ) } ) ` -Architecture X86_64 ` -ImdsSupport v2.0 ``` ------ **To configure an existing AMI for IMDSv2** Use one of the following methods to configure an existing AMI for IMDSv2. ------ #### [ AWS CLI ] The following [modify-image-attribute](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-image-attribute.html) example modifies an existing AMI for IMDSv2 only. Specify `v2.0` for the `imds-support` parameter so that instances launched from this AMI will require that IMDSv2 is used when requesting instance metadata. ``` aws ec2 modify-image-attribute \ --image-id ami-0abcdef1234567890 \ --imds-support v2.0 ``` ------ #### [ PowerShell ] The following [Edit-EC2ImageAttribute](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2ImageAttribute.html) cmdlet example modifies an existing AMI for IMDSv2 only. Specify `v2.0` for the `imds-support` parameter so that instances launched from this AMI will require that IMDSv2 is used when requesting instance metadata. ``` Edit-EC2ImageAttribute ` -ImageId ami-0abcdef1234567890 ` -ImdsSupport 'v2.0' ``` ------ ### Use an IAM policy You can create an IAM policy that does one of the following: + Prevents users from launching new instances unless they require IMDSv2 on the new instance. + Prevents users from calling the ModifyInstanceMetadataOptions API to change the metadata options of a running instance. Restrict access to the ModifyInstanceMetadataOptions httpTokens property to prevent unintended updates of running instances. + Prevent users from calling the ModifyInstanceMetadataDefaults API to change the account default settings of both httpTokens and httpTokensEnforced. Restricting access to these two properties will ensure that only authorized roles can modify the account defaults. **To enforce the use of IMDSv2 on all new instances by using an IAM policy** To ensure that users can only launch instances that require the use of IMDSv2 when requesting instance metadata, do the following: + Restrict access to both `ModifyInstanceMetadataOptions` and `ModifyInstanceMetadataDefaults` API, and more specifically the `httpTokens` and `httpTokensEnforced` properties. + Then, set the account default to `httpTokens = required` and `httpTokensEnforced = enabled`. For the example IAM policy, see [Work with instance metadata](ExamplePolicies_EC2.md#iam-example-instance-metadata). ## Enable the IMDS IPv4 and IPv6 endpoints The IMDS has two endpoints on an instance: IPv4 (`169.254.169.254`) and IPv6 (`[fd00:ec2::254]`). When you enable the IMDS, the IPv4 endpoint is automatically enabled. The IPv6 endpoint remains disabled even if you launch an instance into an IPv6-only subnet. To enable the IPv6 endpoint, you need to do so explicitly. When you enable the IPv6 endpoint, the IPv4 endpoint remains enabled. You can enable the IPv6 endpoint at instance launch or after. **Requirements for enabling the IPv6 endpoint** + The selected instance type is a [Nitro-based instance](instance-types.md#instance-hypervisor-type). + The selected subnet supports IPv6, where the subnet is either [dual stack or IPv6 only](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-ip-address-range). Use any of the following methods to launch an instance with the IMDS IPv6 endpoint enabled. ------ #### [ Console ] **To enable the IMDS IPv6 endpoint at instance launch** + [Launch the instance](ec2-launch-instance-wizard.md) in the Amazon EC2 console with the following specified under **Advanced details**: + For **Metadata IPv6 endpoint**, choose **Enabled**. For more information, see [Advanced details](ec2-instance-launch-parameters.md#liw-advanced-details). ------ #### [ AWS CLI ] **To enable the IMDS IPv6 endpoint at instance launch** The following [run-instances](https://docs.aws.amazon.com/cli/latest/reference/ec2/run-instances.html) example launches a `c6i.large` instance with the IPv6 endpoint enabled for the IMDS. To enable the IPv6 endpoint, for the `--metadata-options` parameter, specify `HttpProtocolIpv6=enabled`. When you specify a value for `HttpProtocolIpv6`, you must also set `HttpEndpoint` to `enabled`. ``` aws ec2 run-instances \ --image-id ami-0abcdef1234567890 \ --instance-type c6i.large \ ... --metadata-options "HttpEndpoint=enabled,HttpProtocolIpv6=enabled" ``` ------ #### [ PowerShell ] **To enable the IMDS IPv6 endpoint at instance launch** The following [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html) cmdlet example launches a `c6i.large` instance with the IPv6 endpoint enabled for the IMDS. To enable the IPv6 endpoint, specify `MetadataOptions_HttpProtocolIpv6` as `enabled`. When you specify a value for `MetadataOptions_HttpProtocolIpv6`, you must also set `MetadataOptions_HttpEndpoint` to `enabled`. ``` New-EC2Instance ` -ImageId ami-0abcdef1234567890 ` -InstanceType c6i.large ` -MetadataOptions_HttpEndpoint enabled ` -MetadataOptions_HttpProtocolIpv6 enabled ``` ------ ## Turn off access to instance metadata You can turn off access to the instance metadata by disabling the IMDS when you launch an instance. You can turn on access later by re-enabling the IMDS. For more information, see [Turn on access to instance metadata](configuring-IMDS-existing-instances.md#enable-instance-metadata-on-existing-instances). **Important** You can choose to disable the IMDS at launch or after launch. If you disable the IMDS *at launch*, the following might not work: You might not have SSH access to your instance. The `public-keys/0/openssh-key`, which is your instance's public SSH key, will not be accessible because the key is normally provided and accessed from EC2 instance metadata. EC2 user data will not be available and will not run at instance start. EC2 user data is hosted on the IMDS. If you disable the IMDS, you effectively turn off access to user data. To access this functionality, you can re-enable the IMDS after launch. ------ #### [ Console ] **To turn off access to instance metadata at launch** + [Launch the instance](ec2-launch-instance-wizard.md) in the Amazon EC2 console with the following specified under **Advanced details**: + For **Metadata accessible**, choose **Disabled**. For more information, see [Advanced details](ec2-instance-launch-parameters.md#liw-advanced-details). ------ #### [ AWS CLI ] **To turn off access to instance metadata at launch at launch** Launch the instance with `--metadata-options` set to `HttpEndpoint=disabled`. ``` aws ec2 run-instances \ --image-id ami-0abcdef1234567890 \ --instance-type c6i.large \ ... --metadata-options "HttpEndpoint=disabled" ``` ------ #### [ PowerShell ] **To turn off access to instance metadata at launch at launch** The following [New-EC2Instance](https://docs.aws.amazon.com/powershell/latest/reference/items/New-EC2Instance.html) cmdlet example launches an instance with `MetadataOptions_HttpEndpoint` set to `disabled`. ``` New-EC2Instance ` -ImageId ami-0abcdef1234567890 ` -InstanceType c6i.large ` -MetadataOptions_HttpEndpoint disabled ``` ------ #### [ CloudFormation ] To specify the metadata options for an instance using CloudFormation, see the [AWS::EC2::LaunchTemplate MetadataOptions](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ec2-launchtemplate-metadataoptions.html) property in the *CloudFormation User Guide*. ------ ## Allow access to tags in instance metadata By default, instance tags are not accessible in the instance metadata. For each instance, you must explicitly allow access. If access is allowed, instance tag *keys* must comply with specific character restrictions, otherwise the instance launch will fail. For more information, see [Enable access to tags in instance metadata](work-with-tags-in-IMDS.md#allow-access-to-tags-in-IMDS). # Modify instance metadata options for existing instances You can modify the instance metadata options for existing instances. You can also create an IAM policy that prevents users from modifying the instance metadata options on existing instances. To control which users can modify the instance metadata options, specify a policy that prevents all users other than users with a specified role to use the [ModifyInstanceMetadataOptions](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataOptions.html) API. For the example IAM policy, see [Work with instance metadata](ExamplePolicies_EC2.md#iam-example-instance-metadata). **Note** If a declarative policy was used to configure the instance metadata options, you can't modify them directly within the account. For more information, see [Declarative policies](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_declarative.html) in the *AWS Organizations User Guide.* ## Require the use of IMDSv2 Use one of the following methods to modify the instance metadata options on an existing instance to require that IMDSv2 is used when requesting instance metadata. When IMDSv2 is required, IMDSv1 cannot be used. **Note** Before requiring that IMDSv2 is used, ensure that the instance isn't making IMDSv1 calls. The `MetadataNoToken` CloudWatch metric tracks IMDSv1 calls. When `MetadataNoToken` records zero IMDSv1 usage for an instance, the instance is then ready to require IMDSv2. ------ #### [ Console ] **To require the use of IMDSv2 on an existing instance** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. In the navigation pane, choose **Instances**. 1. Select your instance. 1. Choose **Actions**, **Instance settings**, **Modify instance metadata options**. 1. In the **Modify instance metadata options** dialog box, do the following: 1. For **Instance metadata service**, select **Enable**. 1. For **IMDSv2**, choose **Required**. 1. Choose **Save**. ------ #### [ AWS CLI ] **To require the use of IMDSv2 on an existing instance** Use the [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) CLI command and set the `http-tokens` parameter to `required`. When you specify a value for `http-tokens`, you must also set `http-endpoint` to `enabled`. ``` aws ec2 modify-instance-metadata-options \ --instance-id i-1234567890abcdef0 \ --http-tokens required \ --http-endpoint enabled ``` ------ #### [ PowerShell ] **To require the use of IMDSv2 on an existing instance** Use the [Edit-EC2InstanceMetadataOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataOption.html) cmdlet and set the `HttpTokens` parameter to `required`. When you specify a value for `HttpTokens`, you must also set `HttpEndpoint` to `enabled`. ``` (Edit-EC2InstanceMetadataOption ` -InstanceId i-1234567890abcdef0 ` -HttpTokens required ` -HttpEndpoint enabled).InstanceMetadataOptions ``` ------ ## Restore the use of IMDSv1 When IMDSv2 is required on an instance, using an IMDSv1 request will fail. When IMDSv2 is optional, then both IMDSv2 and IMDSv1 will work. Therefore, to restore IMDSv1, set IMDSv2 to optional (`httpTokens = optional`) using one of the following methods. The `httpTokensEnforced` IMDS property also prevents attempts to enable IMDSv1 on an existing instance. When enabled for an account in a Region, an attempt to set `httpTokens` to `optional` will result in an `UnsupportedOperation` exception. Fore more information, see [Troubleshooting](#troubleshoot-modifying-an-imdsv1-enabled-instance-fails). **Important** If your instance launches are failing due to IMDSv2 enforcement, you have two options to enable launches to succeed: **Launch instances as IMDSv2-only** – If the software running on the instances uses IMDSv2 only (no dependency on IMDSv1), then you can launch the instances as IMDSv2 only. To do this, configure IMDSv2 only by setting `httpTokens = required` either in the launch parameters or in the metadata defaults for the account in the Region. **Disable enforcement** – If your software still depends on IMDSv1, set `httpTokensEnforced` to `disabled` for the account in the Region. For more information, see [Enforce IMDSv2 at the account level](configuring-IMDS-new-instances.md#enforce-imdsv2-at-the-account-level). ------ #### [ Console ] **To restore the use of IMDSv1 on an instance** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. In the navigation pane, choose **Instances**. 1. Select your instance. 1. Choose **Actions**, **Instance settings**, **Modify instance metadata options**. 1. In the **Modify instance metadata options** dialog box, do the following: 1. For **Instance metadata service**, make sure that **Enable** is selected. 1. For **IMDSv2**, choose **Optional**. 1. Choose **Save**. ------ #### [ AWS CLI ] **To restore the use of IMDSv1 on an instance** You can use the [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) CLI command with `http-tokens` set to `optional` to restore the use of IMDSv1 when requesting instance metadata. ``` aws ec2 modify-instance-metadata-options \ --instance-id i-1234567890abcdef0 \ --http-tokens optional \ --http-endpoint enabled ``` ------ #### [ PowerShell ] **To restore the use of IMDSv1 on an instance** You can use the [Edit-EC2InstanceMetadataOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataOption.html) cmdlet with `HttpTokens` set to `optional` to restore the use of IMDSv1 when requesting instance metadata. ``` (Edit-EC2InstanceMetadataOption ` -InstanceId i-1234567890abcdef0 ` -HttpTokens optional ` -HttpEndpoint enabled).InstanceMetadataOptions ``` ------ ## Change the PUT response hop limit For existing instances, you can change the settings of the `PUT` response hop limit. Currently only the AWS CLI and AWS SDKs support changing the PUT response hop limit. ------ #### [ AWS CLI ] **To change the PUT response hop limit** Use the [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) CLI command and set the `http-put-response-hop-limit` parameter to the required number of hops. In the following example, the hop limit is set to `3`. Note that when specifying a value for `http-put-response-hop-limit`, you must also set `http-endpoint` to `enabled`. ``` aws ec2 modify-instance-metadata-options \ --instance-id i-1234567890abcdef0 \ --http-put-response-hop-limit 3 \ --http-endpoint enabled ``` ------ #### [ PowerShell ] **To change the PUT response hop limit** Use the [Edit-EC2InstanceMetadataOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataOption.html) cmdlet and set the `HttpPutResponseHopLimit` parameter to the required number of hops. In the following example, the hop limit is set to `3`. Note that when specifying a value for `HttpPutResponseHopLimit`, you must also set `HttpEndpoint` to `enabled`. ``` (Edit-EC2InstanceMetadataOption ` -InstanceId i-1234567890abcdef0 ` -HttpPutResponseHopLimit 3 ` -HttpEndpoint enabled).InstanceMetadataOptions ``` ------ ## Enable the IMDS IPv4 and IPv6 endpoints The IMDS has two endpoints on an instance: IPv4 (`169.254.169.254`) and IPv6 (`[fd00:ec2::254]`). When you enable the IMDS, the IPv4 endpoint is automatically enabled. The IPv6 endpoint remains disabled even if you launch an instance into an IPv6-only subnet. To enable the IPv6 endpoint, you need to do so explicitly. When you enable the IPv6 endpoint, the IPv4 endpoint remains enabled. You can enable the IPv6 endpoint at instance launch or after. **Requirements for enabling the IPv6 endpoint** + The selected instance type is a [Nitro-based instance](instance-types.md#instance-hypervisor-type). + The selected subnet supports IPv6, where the subnet is either [dual stack or IPv6 only](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html#subnet-ip-address-range). Currently only the AWS CLI and AWS SDKs support enabling the IMDS IPv6 endpoint after instance launch. ------ #### [ AWS CLI ] **To enable the IMDS IPv6 endpoint for your instance** Use the [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) CLI command and set the `http-protocol-ipv6` parameter to `enabled`. Note that when specifying a value for `http-protocol-ipv6`, you must also set `http-endpoint` to `enabled`. ``` aws ec2 modify-instance-metadata-options \ --instance-id i-1234567890abcdef0 \ --http-protocol-ipv6 enabled \ --http-endpoint enabled ``` ------ #### [ PowerShell ] **To enable the IMDS IPv6 endpoint for your instance** Use the [Edit-EC2InstanceMetadataOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataOption.html) cmdlet and set the `HttpProtocolIpv6` parameter to `enabled`. Note that when specifying a value for `HttpProtocolIpv6`, you must also set `HttpEndpoint` to `enabled`. ``` (Edit-EC2InstanceMetadataOption ` -InstanceId i-1234567890abcdef0 ` -HttpProtocolIpv6 enabled ` -HttpEndpoint enabled).InstanceMetadataOptions ``` ------ ## Turn on access to instance metadata You can turn on access to instance metadata by enabling the HTTP endpoint of the IMDS on your instance, regardless of which version of the IMDS you are using. You can reverse this change at any time by disabling the HTTP endpoint. Use one of the following methods to turn on access to instance metadata on an instance. ------ #### [ Console ] **To turn on access to instance metadata** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. In the navigation pane, choose **Instances**. 1. Select your instance. 1. Choose **Actions**, **Instance settings**, **Modify instance metadata options**. 1. In the **Modify instance metadata options** dialog box, do the following: 1. For **Instance metadata service**, select **Enable**. 1. Choose **Save**. ------ #### [ AWS CLI ] **To turn on access to instance metadata** Use the [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) CLI command and set the `http-endpoint` parameter to `enabled`. ``` aws ec2 modify-instance-metadata-options \ --instance-id i-1234567890abcdef0 \ --http-endpoint enabled ``` ------ #### [ PowerShell ] **To turn on access to instance metadata** Use the [Edit-EC2InstanceMetadataOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataOption.html) cmdlet and set the `HttpEndpoint` parameter to `enabled`. ``` (Edit-EC2InstanceMetadataOption ` -InstanceId i-1234567890abcdef0 ` -HttpEndpoint enabled).InstanceMetadataOptions ``` ------ ## Turn off access to instance metadata You can turn off access to instance metadata by disabling the HTTP endpoint of the IMDS on your instance, regardless of which version of the IMDS you are using. You can reverse this change at any time by enabling the HTTP endpoint. Use one of the following methods to turn off access to instance metadata on an instance. ------ #### [ Console ] **To turn off access to instance metadata** 1. Open the Amazon EC2 console at [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/). 1. In the navigation pane, choose **Instances**. 1. Select your instance. 1. Choose **Actions**, **Instance settings**, **Modify instance metadata options**. 1. In the **Modify instance metadata options** dialog box, do the following: 1. For **Instance metadata service**, clear **Enable**. 1. Choose **Save**. ------ #### [ AWS CLI ] **To turn off access to instance metadata** Use the [modify-instance-metadata-options](https://docs.aws.amazon.com/cli/latest/reference/ec2/modify-instance-metadata-options.html) CLI command and set the `http-endpoint` parameter to `disabled`. ``` aws ec2 modify-instance-metadata-options \ --instance-id i-1234567890abcdef0 \ --http-endpoint disabled ``` ------ #### [ PowerShell ] **To turn off access to instance metadata** Use the [Edit-EC2InstanceMetadataOption](https://docs.aws.amazon.com/powershell/latest/reference/items/Edit-EC2InstanceMetadataOption.html) cmdlet and set the `HttpEndpoint` parameter to `disabled`. ``` (Edit-EC2InstanceMetadataOption ` -InstanceId i-1234567890abcdef0 ` -HttpEndpoint disabled).InstanceMetadataOptions ``` ------ ## Allow access to tags in instance metadata You can allow access to tags in the instance metadata on a running or stopped instance. For each instance, you must explicitly allow access. If access is allowed, instance tag *keys* must comply with specific character restrictions, otherwise you get an error. For more information, see [Enable access to tags in instance metadata](work-with-tags-in-IMDS.md#allow-access-to-tags-in-IMDS). ## Troubleshooting ### Modifying an IMDSv1-enabled instance fails #### Description You get the following error message: `You can't launch instances with IMDSv1 because httpTokensEnforced is enabled for this account. Either launch the instance with httpTokens=required or contact your account owner to disable httpTokensEnforced using the ModifyInstanceMetadataDefaults API or the account settings in the EC2 console.` #### Cause This error is thrown when you attempt to modify an existing instance to be IMDSv1 enabled (`httpTokens = optional`) in an account where the EC2 account settings or an AWS Organization declarative policy enforces the use of IMDSv2 (`httpTokensEnforced = enabled`). #### Solution If you require IMDSv1 support on existing instances, you'll need to disable IMDSv2 enforcement for the account in the Region. To disable IMDSv2 enforcement, set `HttpTokensEnforced` to `disabled`. For more information, see [ModifyInstanceMetadataDefaults](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_ModifyInstanceMetadataDefaults.html) in the Amazon EC2 API Reference. If you prefer to configure this setting using the console, see [Enforce IMDSv2 at the account level](configuring-IMDS-new-instances.md#enforce-imdsv2-at-the-account-level). We recommend that you use IMDSv2 only (`httpTokens=required`). For more information, see [Transition to using Instance Metadata Service Version 2](instance-metadata-transition-to-version-2.md).