How IMDSv2 works Transition to using IMDSv2 Supported SDKs Examples for IMDSv2 Examples for IMDSv1

Use the Instance Metadata Service to access instance metadata

You can access instance metadata from a running instance using one of the following methods:

Instance Metadata Service Version 2 (IMDSv2) – a session-oriented method

For examples, see Examples for IMDSv2.
Instance Metadata Service Version 1 (IMDSv1) – a request/response method

For examples, see Examples for IMDSv1.

By default, you can use either IMDSv1 or IMDSv2, or both.

You can configure the Instance Metadata Service (IMDS) on each instance so that local code or users must use IMDSv2. When you specify that IMDSv2 must be used, IMDSv1 no longer works. For information about how to configure your instance to use IMDSv2, see Configure the Instance Metadata Service options.

The PUT or GET headers are unique to IMDSv2. If these headers are present in the request, then the request is intended for IMDSv2. If no headers are present, it is assumed the request is intended for IMDSv1.

For an extensive review of IMDSv2, see Add defense in depth against open firewalls, reverse proxies, and SSRF vulnerabilities with enhancements to the EC2 Instance Metadata Service.

Topics

How Instance Metadata Service Version 2 works
Transition to using Instance Metadata Service Version 2
Use a supported AWS SDK
Examples for IMDSv2
Examples for IMDSv1

How Instance Metadata Service Version 2 works

IMDSv2 uses session-oriented requests. With session-oriented requests, you create a session token that defines the session duration, which can be a minimum of one second and a maximum of six hours. During the specified duration, you can use the same session token for subsequent requests. After the specified duration expires, you must create a new session token to use for future requests.

Note

The examples in this section use the IPv4 address of the Instance Metadata Service (IMDS): 169.254.169.254. If you are retrieving instance metadata for EC2 instances over the IPv6 address, ensure that you enable and use the IPv6 address instead: [fd00:ec2::254]. The IPv6 address of the IMDS is compatible with IMDSv2 commands. The IPv6 address is only accessible on instances built on the AWS Nitro System and in an IPv6-supported subnet (dual stack or IPv6 only).

The following examples use a shell script and IMDSv2 to retrieve the top-level instance metadata items. Each example:

Creates a session token lasting six hours (21,600 seconds) using the PUT request
Stores the session token header in a variable named TOKEN (Linux instances) or token (Windows instances)
Requests the top-level metadata items using the token

You can run two separate commands, or combine them.

Separate commands

First, generate a token using the following command.


[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"`

Then, use the token to generate top-level metadata items using the following command.


[ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/

Combined commands

You can store the token and combine the commands. The following example combines the above two commands and stores the session token header in a variable named TOKEN.

Note

If there is an error in creating the token, instead of a valid token, an error message is stored in the variable, and the command will not work.


[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
	&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/

After you've created a token, you can reuse it until it expires. In the following example command, which gets the ID of the AMI used to launch the instance, the token that is stored in $TOKEN in the previous example is reused.


[ec2-user ~]$ curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/ami-id


PS C:\> [string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token


PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/meta-data/


PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} `
	-Method GET -uri http://169.254.169.254/latest/meta-data/ami-id

When you use IMDSv2 to request instance metadata, the request must include the following:

Use a PUT request to initiate a session to the instance metadata service. The PUT request returns a token that must be included in subsequent GET requests to the instance metadata service. The token is required to access metadata using IMDSv2.
Include the token in all GET requests to the IMDS. When token usage is set to required, requests without a valid token or with an expired token receive a 401 - Unauthorized HTTP error code.
- The token is an instance-specific key. The token is not valid on other EC2 instances and will be rejected if you attempt to use it outside of the instance on which it was generated.
- The PUT request must include a header that specifies the time to live (TTL) for the token, in seconds, up to a maximum of six hours (21,600 seconds). The token represents a logical session. The TTL specifies the length of time that the token is valid and, therefore, the duration of the session.
- After a token expires, to continue accessing instance metadata, you must create a new session using another PUT.
- You can choose to reuse a token or create a new token with every request. For a small number of requests, it might be easier to generate and immediately use a token each time you need to access the IMDS. But for efficiency, you can specify a longer duration for the token and reuse it rather than having to write a PUT request every time you need to request instance metadata. There is no practical limit on the number of concurrent tokens, each representing its own session. IMDSv2 is, however, still constrained by normal IMDS connection and throttling limits. For more information, see Query throttling.

HTTP GET and HEAD methods are allowed in IMDSv2 instance metadata requests. PUT requests are rejected if they contain an X-Forwarded-For header.

By default, the response to PUT requests has a response hop limit (time to live) of 1 at the IP protocol level. If you need a bigger hop limit, you can adjust it by using the modify-instance-metadata-options AWS CLI command. For example, you might need a bigger hop limit for backward compatibility with container services running on the instance. For more information, see Modify instance metadata options for existing instances.

Transition to using Instance Metadata Service Version 2

When migrating to IMDSv2, we recommend that you use the following tools and transition path.

Topics

Tools for helping with the transition to IMDSv2
Recommended path to requiring IMDSv2

Tools for helping with the transition to IMDSv2

If your software uses IMDSv1, use the following tools to help reconfigure your software to use IMDSv2.

AWS software

The latest versions of the AWS CLI and AWS SDKs support IMDSv2. To use IMDSv2, make sure that your EC2 instances have the latest versions of the CLI and SDKs. For information about updating the CLI, see Installing, updating, and uninstalling the AWS CLI in the AWS Command Line Interface User Guide.

All Amazon Linux 2 and Amazon Linux 2023 software packages support IMDSv2. In Amazon Linux 2023, IMDSv1 is disabled by default.

For the minimum AWS SDK versions that support IMDSv2, see Use a supported AWS SDK.

IMDS Packet Analyzer

The IMDS Packet Analyzer is an open-sourced tool that identifies and logs IMDSv1 calls from your instance’s boot phase. This can assist in identifying the software making IMDSv1 calls on EC2 instances, allowing you to pinpoint exactly what you need to update to get your instances ready to use IMDSv2 only. You can run IMDS Packet Analyzer from a command line or install it as a service. For more information, see IMDS Packet Analyzer on GitHub.

CloudWatch

IMDSv2 uses token-backed sessions, while IMDSv1 does not. The MetadataNoToken CloudWatch metric tracks the number of calls to the Instance Metadata Service (IMDS) that are using IMDSv1. By tracking this metric to zero, you can determine if and when all of your software has been upgraded to use IMDSv2.

After you've disabled IMDSv1, you can use the MetadataNoTokenRejected CloudWatch metric to track the number of times an IMDSv1 call was attempted and rejected. By tracking this metric, you can ascertain whether your software needs to be updated to use IMDSv2.

For more information, see Instance metrics.

Updates to EC2 APIs and CLIs

For new instances, you can use the RunInstances API to launch new instances that require the use of IMDSv2. For more information, see Configure instance metadata options for new instances.

For existing instances, you can use the ModifyInstanceMetadataOptions API to require the use of IMDSv2. For more information, see Modify instance metadata options for existing instances.

To require the use of IMDSv2 on all new instances launched by Auto Scaling groups, your Auto Scaling groups can use either a launch template or a launch configuration. When you create a launch template or create a launch configuration, you must configure the MetadataOptions parameters to require the use of IMDSv2. The Auto Scaling group launches new instances using the new launch template or launch configuration, but existing instances are not affected. For existing instances in an Auto Scaling group, you can use the ModifyInstanceMetadataOptions API to require the use of IMDSv2 on the existing instances, or terminate the instances and the Auto Scaling group will launch new replacement instances with the instance metadata options settings that are defined in the new launch template or launch configuration.

Use an AMI that configures IMDSv2 by default

When you launch an instance, you can automatically configure it to use IMDSv2 by default (the HttpTokens parameter is set to required) by launching it with an AMI that is configured with the ImdsSupport parameter set to v2.0. You can set the ImdsSupport parameter to v2.0 when you register the AMI using the register-image CLI command, or you can modify an existing AMI by using the modify-image-attribute CLI command. For more information, see Configure the AMI.

IAM policies and SCPs

You can use an IAM policy or AWS Organizations service control policy (SCP) to control users as follows:

Can't launch an instance using the RunInstances API unless the instance is configured to use IMDSv2.
Can't modify a running instance using the ModifyInstanceMetadataOptions API to re-enable IMDSv1.

The IAM policy or SCP must contain the following IAM condition keys:

ec2:MetadataHttpEndpoint
ec2:MetadataHttpPutResponseHopLimit
ec2:MetadataHttpTokens

If a parameter in the API or CLI call does not match the state specified in the policy that contains the condition key, the API or CLI call fails with an UnauthorizedOperation response.

Furthermore, you can choose an additional layer of protection to enforce the change from IMDSv1 to IMDSv2. At the access management layer with respect to the APIs called via EC2 Role credentials, you can use a new condition key in either IAM policies or AWS Organizations service control policies (SCPs). Specifically, by using the condition key ec2:RoleDelivery with a value of 2.0 in your IAM policies, API calls made with EC2 Role credentials obtained from IMDSv1 will receive an UnauthorizedOperation response. The same thing can be achieved more broadly with that condition required by an SCP. This ensures that credentials delivered via IMDSv1 cannot actually be used to call APIs because any API calls not matching the specified condition will receive an UnauthorizedOperation error.

For example IAM policies, see Work with instance metadata. For more information on SCPs, see Service Control Policies in the AWS Organizations User Guide.

Recommended path to requiring IMDSv2

Using the above tools, we recommend that you follow this path for transitioning to IMDSv2.

Step 1: At the start

Update the SDKs, CLIs, and your software that use Role credentials on their EC2 instances to versions compatible with IMDSv2. For information about updating the CLI, see Upgrading to the latest version of the AWS CLI in the AWS Command Line Interface User Guide.

Then, change your software that directly accesses instance metadata (in other words, that does not use an SDK) using the IMDSv2 requests. You can use the IMDS Packet Analyzer to identify the software that you need to change to use IMDSv2 requests.

Step 2: Track your transition progress

Track your transition progress by using the CloudWatch metric MetadataNoToken. This metric shows the number of IMDSv1 calls to the IMDS on your instances. For more information, see Instance metrics.

Step 3: When there is zero IMDSv1 usage

When the CloudWatch metric MetadataNoToken records zero IMDSv1 usage, your instances are ready to be fully transitioned to using IMDSv2. At this stage, you can do the following:

Account default

You can set IMDSv2 to be required as an account default. When an instance is launched, the instance configuration is automatically set to the account default.

To set the account default, do the following:
- Amazon EC2 console: On the EC2 Dashboard, under Account attributes, Data protection and security, for IMDS defaults, set Instance metadata service to Enabled and Metadata version to V2 only (token required). For more information, see Set IMDSv2 as the default for the account.
- AWS CLI: Use the modify-instance-metadata-defaults CLI command and specify --http-tokens required and --http-put-response-hop-limit 2.
New instances

When launching a new instance, you can do the following:
- Amazon EC2 console: In the launch instance wizard, set Metadata accessible to Enabled and Metadata version to V2 only (token required). For more information, see Configure the instance at launch.
- AWS CLI: Use the run-instances CLI command and specify that IMDSv2 is required.
Existing instances

For existing instances, you can do the following:
- Amazon EC2 console: On the Instances page, select your instance, choose Actions, Instance settings, Modify instance metadata options, and for IMDSv2, choose Required. For more information, see Require the use of IMDSv2.
- AWS CLI: Use the modify-instance-metadata-options CLI command to specify that only IMDSv2 is to be used.
You can modify the instance metadata options on running instances, and you don't need to restart the instances after modifying the instance metadata options.

Step 4: Check if your instances are transitioned to IMDSv2

You can check if any instances are not yet configured to require the use of IMDSv2, in other words, IMDSv2 is still configured as optional. If any instances are still configured as optional, you can modify the instance metadata options to make IMDSv2 required by repeating the preceding Step 3.

To filter your instances:

Amazon EC2 console: On the Instances page, filter your instances by using the IMDSv2 = optional filter. For more information about filtering, see Filter resources using the console. You can also view whether IMDSv2 is required or optional for each instance: In the Preferences window, toggle on IMDSv2 to add the IMDSv2 column to the Instances table.

AWS CLI: Use the describe-instances CLI command and filter by metadata-options.http-tokens = optional, as follows:


aws ec2 describe-instances --filters "Name=metadata-options.http-tokens,Values=optional" --query "Reservations[*].Instances[*].[InstanceId]" --output text

Step 5: When all of your instances are transitioned to IMDSv2

The ec2:MetadataHttpTokens, ec2:MetadataHttpPutResponseHopLimit, and ec2:MetadataHttpEndpoint IAM condition keys can be used to control the use of the RunInstances and the ModifyInstanceMetadataOptions APIs and corresponding CLIs. If a policy is created, and a parameter in the API call does not match the state specified in the policy using the condition key, the API or CLI call fails with an UnauthorizedOperation response. For example IAM policies, see Work with instance metadata.

Furthermore, after you've disabled IMDSv1, you can use the MetadataNoTokenRejected CloudWatch metric to track the number of times an IMDSv1 call was attempted and rejected. If, after disabling IMDSv1, you have software that is not working properly and the MetadataNoTokenRejected metric records IMDSv1 calls, it's likely that this software needs to be updated to use IMDSv2.

Use a supported AWS SDK

To use IMDSv2, your EC2 instances must use an AWS SDK version that supports using IMDSv2. The latest versions of all the AWS SDKs support using IMDSv2.

Important

We recommend that you to stay up to date with SDK releases to keep up with the latest features, security updates, and underlying dependencies. Continued use of an unsupported SDK version is not recommended and is done at your discretion. For more information, see the AWS SDKs and Tools maintenance policy in the AWS SDKs and Tools Reference Guide.

The following are the minimum versions that support using IMDSv2:

AWS CLI – 1.16.289
AWS Tools for Windows PowerShell – 4.0.1.0
AWS SDK for .NET – 3.3.634.1
AWS SDK for C++ – 1.7.229
AWS SDK for Go – 1.25.38
AWS SDK for Go v2 – 0.19.0
AWS SDK for Java – 1.11.678
AWS SDK for Java 2.x – 2.10.21
AWS SDK for JavaScript in Node.js – 2.722.0
AWS SDK for PHP – 3.147.7
AWS SDK for Python (Botocore) – 1.13.25
AWS SDK for Python (Boto3) – 1.12.6
AWS SDK for Ruby – 3.79.0

Examples for IMDSv2

Run the following examples on your Amazon EC2 instance to retrieve the instance metadata for IMDSv2.

On Windows instances, you can use Windows PowerShell or you can install cURL or wget. If you install a third-party tool on a Windows instance, ensure that you read the accompanying documentation carefully, as the calls and the output might be different from what is described here.

Examples

Get the available versions of the instance metadata
Get the top-level metadata items
Get the values for metadata items
Get the list of available public keys
Show the formats in which public key 0 is available
Get public key 0 (in the OpenSSH key format)
Get the subnet ID for an instance
Get the instance tags for an instance

Get the available versions of the instance metadata

This example gets the available versions of the instance metadata. Each version refers to an instance metadata build when new instance metadata categories were released. The instance metadata build versions do not correlate with the Amazon EC2 API versions. The earlier versions are available to you in case you have scripts that rely on the structure and information present in a previous version.

Get the top-level metadata items

This example gets the top-level metadata items. For more information about the items in the response, see Instance metadata categories.

Note that tags are included in this output only if you've allowed access. For more information, see Allow access to tags in instance metadata.

Get the values for metadata items

These examples get the values of some of the top-level metadata items that were obtained in the preceding example. These requests use the stored token that was created using the command in the previous example. The token must not be expired.

Get the list of available public keys

This example gets the list of available public keys.

Show the formats in which public key 0 is available

This example shows the formats in which public key 0 is available.

Get public key 0 (in the OpenSSH key format)

This example gets public key 0 (in the OpenSSH key format).

cURL


[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/public-keys/0/openssh-key
ssh-rsa MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w0BAQUFADCBiDELMAkGA1UEBhMC
VVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6
b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAd
BgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wHhcNMTEwNDI1MjA0NTIxWhcN
MTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYD
VQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25z
b2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFt
YXpvbi5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ
21uUSfwfEvySWtC2XADZ4nB+BLYgVIk60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9T
rDHudUZg3qX4waLG5M43q7Wgc/MbQITxOUSQv7c7ugFFDzQGBzZswY6786m86gpE
Ibb3OhjZnzcvQAaRHhdlQWIMm2nrAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4
nUhVVxYUntneD9+h8Mg9q6q+auNKyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0Fkb
FFBjvSfpJIlJ00zbhNYS5f6GuoEDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTb
NYiytVbZPQUQ5Yaxu2jXnimvw3rrszlaEXAMPLE my-public-key

PowerShell


PS C:\> [string]$token = Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token-ttl-seconds" = "21600"} -Method PUT -Uri http://169.254.169.254/latest/api/token


PS C:\> Invoke-RestMethod -Headers @{"X-aws-ec2-metadata-token" = $token} -Method GET -Uri http://169.254.169.254/latest/meta-data/public-keys/0/openssh-key
ssh-rsa MIICiTCCAfICCQD6m7oRw0uXOjANBgkqhkiG9w0BAQUFADCBiDELMAkGA1UEBhMC
VVMxCzAJBgNVBAgTAldBMRAwDgYDVQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6
b24xFDASBgNVBAsTC0lBTSBDb25zb2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAd
BgkqhkiG9w0BCQEWEG5vb25lQGFtYXpvbi5jb20wHhcNMTEwNDI1MjA0NTIxWhcN
MTIwNDI0MjA0NTIxWjCBiDELMAkGA1UEBhMCVVMxCzAJBgNVBAgTAldBMRAwDgYD
VQQHEwdTZWF0dGxlMQ8wDQYDVQQKEwZBbWF6b24xFDASBgNVBAsTC0lBTSBDb25z
b2xlMRIwEAYDVQQDEwlUZXN0Q2lsYWMxHzAdBgkqhkiG9w0BCQEWEG5vb25lQGFt
YXpvbi5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAMaK0dn+a4GmWIWJ
21uUSfwfEvySWtC2XADZ4nB+BLYgVIk60CpiwsZ3G93vUEIO3IyNoH/f0wYK8m9T
rDHudUZg3qX4waLG5M43q7Wgc/MbQITxOUSQv7c7ugFFDzQGBzZswY6786m86gpE
Ibb3OhjZnzcvQAaRHhdlQWIMm2nrAgMBAAEwDQYJKoZIhvcNAQEFBQADgYEAtCu4
nUhVVxYUntneD9+h8Mg9q6q+auNKyExzyLwaxlAoo7TJHidbtS4J5iNmZgXL0Fkb
FFBjvSfpJIlJ00zbhNYS5f6GuoEDmFJl0ZxBHjJnyp378OD8uTs7fLvjx79LjSTb
NYiytVbZPQUQ5Yaxu2jXnimvw3rrszlaEXAMPLE my-public-key

Get the subnet ID for an instance

This example gets the subnet ID for an instance.

Get the instance tags for an instance

If access to instance tags in the instance metadata is turned on, you can get the tags for a instance from instance metadata. For more information, see Retrieve tags from instance metadata.

Examples for IMDSv1

Run the following examples on your Amazon EC2 instance to retrieve the instance metadata for IMDSv1.