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).
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 API. For the example IAM policy, see
Work with instance metadata.
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 in the Amazon 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.
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
Open the Amazon EC2 console at
https://console.amazonaws.cn/ec2/.
-
In the navigation pane, choose
Instances.
-
Select your instance.
-
Choose Actions, Instance
settings, Modify instance metadata
options.
-
In the Modify instance metadata
options dialog box, do the following:
-
For Instance metadata
service, select
Enable.
-
For IMDSv2, choose
Required.
-
Choose Save.
- Amazon CLI
-
To require the use of IMDSv2 on an existing
instance
Use the modify-instance-metadata-options 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-1234567898abcdef0
\
--http-tokens required \
--http-endpoint enabled
- PowerShell
-
To require the use of IMDSv2 on an existing
instance
Use the Edit-EC2InstanceMetadataOption 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-1234567898abcdef0
`
-HttpTokens required `
-HttpEndpoint enabled).InstanceMetadataOptions
Restore the use of IMDSv1
When IMDSv2 is required, IMDSv1 will not work when requesting instance
metadata. When IMDSv2 is optional, then both IMDSv2 and IMDSv1 will work.
Therefore, to restore IMDSv1, make IMDSv2 optional by using one of the following
methods.
- Console
-
To restore the use of IMDSv1 on an instance
Open the Amazon EC2 console at
https://console.amazonaws.cn/ec2/.
-
In the navigation pane, choose
Instances.
-
Select your instance.
-
Choose Actions, Instance
settings, Modify instance metadata
options.
-
In the Modify instance metadata
options dialog box, do the following:
-
For Instance metadata
service, make sure that
Enable is selected.
-
For IMDSv2, choose
Optional.
-
Choose Save.
- Amazon CLI
-
To restore the use of IMDSv1 on an instance
You can use the modify-instance-metadata-options 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-1234567898abcdef0
\
--http-tokens optional \
--http-endpoint enabled
- PowerShell
-
To restore the use of IMDSv1 on an instance
You can use the Edit-EC2InstanceMetadataOption Cmdlet with
HttpTokens
set to optional
to
restore the use of IMDSv1 when requesting instance
metadata.
(Edit-EC2InstanceMetadataOption `
-InstanceId i-1234567898abcdef0
`
-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 Amazon CLI and Amazon SDKs support changing the PUT response hop
limit.
- Amazon CLI
-
To change the PUT response hop limit
Use the modify-instance-metadata-options 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-1234567898abcdef0
\
--http-put-response-hop-limit 3
\
--http-endpoint enabled
- PowerShell
-
To change the PUT response hop limit
Use the Edit-EC2InstanceMetadataOption 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-1234567898abcdef0
`
-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
Currently only the Amazon CLI and Amazon SDKs support enabling the IMDS IPv6
endpoint after instance launch.
- Amazon CLI
-
To enable the IMDS IPv6 endpoint for your instance
Use the modify-instance-metadata-options 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-1234567898abcdef0
\
--http-protocol-ipv6 enabled \
--http-endpoint enabled
- PowerShell
-
To enable the IMDS IPv6 endpoint for your instance
Use the Edit-EC2InstanceMetadataOption 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-1234567898abcdef0
`
-HttpProtocolIpv6 enabled `
-HttpEndpoint enabled).InstanceMetadataOptions
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
Open the Amazon EC2 console at
https://console.amazonaws.cn/ec2/.
-
In the navigation pane, choose
Instances.
-
Select your instance.
-
Choose Actions, Instance
settings, Modify instance metadata
options.
-
In the Modify instance metadata
options dialog box, do the following:
-
For Instance metadata
service, select
Enable.
-
Choose Save.
- Amazon CLI
-
To turn on access to instance metadata
Use the modify-instance-metadata-options CLI command and
set the http-endpoint
parameter to
enabled
.
aws ec2 modify-instance-metadata-options \
--instance-id i-1234567898abcdef0
\
--http-endpoint enabled
- PowerShell
-
To turn on access to instance metadata
Use the Edit-EC2InstanceMetadataOption Cmdlet and set the
HttpEndpoint
parameter to
enabled
.
(Edit-EC2InstanceMetadataOption `
-InstanceId i-1234567898abcdef0
`
-HttpEndpoint enabled).InstanceMetadataOptions
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
Open the Amazon EC2 console at
https://console.amazonaws.cn/ec2/.
-
In the navigation pane, choose
Instances.
-
Select your instance.
-
Choose Actions, Instance
settings, Modify instance metadata
options.
-
In the Modify instance metadata
options dialog box, do the following:
-
For Instance metadata
service, clear
Enable.
-
Choose Save.
- Amazon CLI
-
To turn off access to instance metadata
Use the modify-instance-metadata-options CLI command and
set the http-endpoint
parameter to
disabled
.
aws ec2 modify-instance-metadata-options \
--instance-id i-1234567898abcdef0
\
--http-endpoint disabled
- PowerShell
-
To turn off access to instance metadata
Use the Edit-EC2InstanceMetadataOption Cmdlet and set the
HttpEndpoint
parameter to
disabled
.
(Edit-EC2InstanceMetadataOption `
-InstanceId i-1234567898abcdef0
`
-HttpEndpoint disabled).InstanceMetadataOptions
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 Allow access to tags in instance metadata.