This topic was translated by AI and is currently in queue for revision by our editors. Alibaba Cloud does not guarantee the accuracy of AI-translated content. Request expedited revision
Home PageElastic Compute ServiceUser GuideInstancesManage instancesInstance metadata
Search for Help Content

Instance metadata

Updated at: 2025-03-26 18:00
Product
Community

ECS instance metadata refers to instance property information such as instance ID, VPC information, and network interface information. You can access this information from within an ECS instance through the metadata service. This method allows you to access instance information without logging on to the console or calling API operations, making it more convenient and secure to configure or manage running instances or applications on instances.

Instance metadata list

The metadata service allows you to obtain information such as hostname, instance type, instance name, and image ID. Expand the following table to view all metadata items.

Click to expand

Metadata

Description

Example

dns-conf/nameservers

The Domain Name System (DNS) configurations of the instance.

100.100.XX.XX

hostname

The hostname of the instance.

iZbp13znx0m0me8cquu****

instance/instance-type

The instance type.

ecs.g6e.large

instance/instance-name

The instance name.

iZbp1bfqfsvqzxhmnd5****

image-id

The ID of the image that is used to create the instance.

aliyun_3_x64_20G_alibase_20210425.vhd

image/market-place/product-code

The product code of the Alibaba Cloud Marketplace image.

cmjj01****

image/market-place/charge-type

The billing method of the Alibaba Cloud Marketplace image.

PrePaid

instance-id

The ID of the instance.

i-bp13znx0m0me8cquu****

mac

The media access control (MAC) address of the instance. If the instance has multiple NICs, only the MAC address of the eth0 NIC is displayed.

00:16:3e:0f:XX:XX

network-type

The network type of the instance. Only instances that are deployed in VPCs support this metadata item.

vpc

network/interfaces/macs/[mac]/network-interface-id

The ID of the NIC. The [mac] parameter must be replaced with the MAC address of the instance.

eni-bp1b2c0jvnj0g17b****

network/interfaces/macs/[mac]/netmask

The subnet mask of the NIC.

255.255.XX.XX

network/interfaces/macs/[mac]/vswitch-cidr-block

The IPv4 CIDR block of the vSwitch to which the NIC is connected.

192.168.XX.XX/24

network/interfaces/macs/[mac]/vpc-cidr-block

The IPv4 CIDR block of the VPC to which the NIC belongs.

192.168.XX.XX/16

network/interfaces/macs/[mac]/private-ipv4s

The private IPv4 addresses that are assigned to the NIC.

["192.168.XX.XX"]

network/interfaces/macs/[mac]/vswitch-id

The ID of the vSwitch to which the NIC belongs.

vsw-bp1ygryo03m39xhsy****

network/interfaces/macs/[mac]/vpc-id

The ID of the VPC to which the security group of the NIC belongs.

vpc-bp1e0g399hkd7c8q3****

network/interfaces/macs/[mac]/primary-ip-address

The primary private IP address of the NIC.

192.168.XX.XX

network/interfaces/macs/[mac]/gateway

The IPv4 gateway address of the NIC.

192.168.XX.XX

instance/max-netbw-egress

The maximum outbound internal bandwidth of the instance. Unit: Kbit/s.

1228800

network/interfaces/macs/[mac]/ipv4-prefixes

The private IPv4 prefix lists that are assigned to the NIC.

192.168.XX.XX/28

network/interfaces/macs/[mac]/ipv6-prefixes

The private IPv6 prefix lists that are assigned to the NIC.

2001:db8:1234:1a00:XXXX::/80

disks/

The serial number of the disk.

bp131n0q38u3a4zi****

disks/[disk-serial]/id

The ID of the disk.

d-bp131n0q38u3a4zi****

disks/[disk-serial]/name

The name of the disk.

testDiskName

private-ipv4

The private IPv4 address of the primary NIC.

192.168.XX.XX

public-ipv4

The public IPv4 address of the primary NIC.

120.55.XX.XX

eipv4

This metadata item is used to obtain the following information:

  • The system-assigned public IPv4 address of the instance.

  • The elastic IPv4 address associated with the primary NIC.

120.55.XX.XX

ntp-conf/ntp-servers

The NTP server address.

ntp1.aliyun.com

owner-account-id

The ID of the Alibaba Cloud account to which the instance belongs.

1609****

region-id

The region ID of the instance.

cn-hangzhou

zone-id

The zone ID of the instance.

cn-hangzhou-i

public-keys/[keypair-id]/openssh-key

The public key. This metadata item is available only if a public key is bound to an instance during instance creation.

ssh-rsa ****3NzaC1yc2EAAAADAQABAAABAQDLNbE7pS****@****.com

serial-number

The serial number of the instance.

4acd2b47-b328-4762-852f-998****

source-address

The address of the YUM or APT image repository. The package management software of a Linux instance can obtain updates from the image repository.

http://mirrors.cloud.aliyuncs.com

kms-server

The Key Management Service (KMS) server that is used by the Windows instance to activate Windows.

kms.cloud.aliyuncs.com

wsus-server/wu-server

The update server of the Windows instance.

http://update.cloud.aliyuncs.com

wsus-server/wu-status-server

The server that monitors the update status of the Windows instance.

http://update.cloud.aliyuncs.com

vpc-id

The ID of the VPC to which the instance belongs.

vpc-bp1e0g399hkd7c8q****

vpc-cidr-block

The CIDR block of the VPC to which the instance belongs.

192.168.XX.XX/16

vswitch-cidr-block

The CIDR block of the vSwitch to which the instance is connected.

192.168.XX.XX/24

vswitch-id

The ID of the vSwitch to which the instance is connected.

vsw-bp1ygryo03m39xhsy****

ram/security-credentials/[role-name]

If a RAM role is attached to the instance, role-name is the name of the role, and the response contains the temporary security credentials that are associated with the role-name role.

The credentials expire at the time specified in the Expiration field. You must call the operation again to obtain new credentials.

 
{
  "AccessKeyId" : "****",
  "AccessKeySecret" : "****",
  "Expiration" : "2024-11-08T09:44:50Z",
  "SecurityToken" : "****",
  "LastUpdated" : "2024-11-08T03:44:50Z",
  "Code" : "Success"
}

instance/spot/termination-time

The stop time and release time that are configured in the operating system of the preemptible instance. The time is in the yyyy-MM-ddThh:mm:ssZ format. The time is displayed in UTC.

2020-04-07T17:03:00Z

instance/virtualization-solution

The ECS virtualization solution. Virt 1.0 and Virt 2.0 are supported.

ECS Virt

instance/virtualization-solution-version

The version of the ECS virtualization solution.

2.0

Metadata access modes

There are two metadata access modes: normal mode and security hardening mode. For information about how to access metadata, see Access instance metadata. The following table compares the two modes.

Important

We recommend that you use the security hardening mode to access instance metadata. The normal mode authenticates requests based on IP addresses. This means that attackers can forge the source IP addresses in requests to bypass IP address-based authentication and launch server-side request forgery (SSRF) attacks. As a result, instance metadata may be leaked.

To access metadata in security hardening mode, make sure that the cloud-init version on the instance is 23.2.2 or later. If the cloud-init version on an existing ECS instance is not 23.2.2, you can upgrade the cloud-init version to 23.2.2 to support the security hardening mode. For information about how to check and upgrade the cloud-init version, see Install cloud-init.

Comparison of access modes

Item

Normal mode

Security hardening mode

Item

Normal mode

Security hardening mode

Interaction method

Request-response

Session

Authentication method

Use source IP addresses in the same VPC for authentication

Use source IP addresses in the same VPC and metadata server access credentials for authentication

Metadata server access credentials have the following characteristics:

  • Short validity period: Metadata server access credentials have a validity period of up to 6 hours. After the validity period ends, the credentials expire and you must obtain new credentials.

  • Metadata server access credentials are tied to ECS instances: Metadata server access credentials are tied to ECS instances. If you copy the metadata server access credentials of an ECS instance to access another ECS instance, your access is denied.

  • No proxy access: If a request contains the X-Forwarded-For header, the metadata server rejects to issue access credentials.

Access method

Use commands to access the endpoint without access credentials

Obtain metadata server access credentials for authentication before you access the endpoint, which enhances the security of metadata access

Security level

Lower

Requests are authenticated based on IP addresses. Attackers can forge the source IP addresses in requests to bypass IP address-based authentication and launch SSRF attacks. As a result, instance metadata may be leaked.

Higher

Before you can access instance metadata, you must obtain valid metadata server access credentials for authentication and authorization. Metadata server access credentials are generated in ECS instances and are tied to the ECS instances. Metadata server access credentials have a validity period. Metadata server access credentials are difficult for attackers to guess or forge and help you defend against most SSRF attacks.

Access instance metadata by using different modes

Security hardening mode
Normal mode

  • Linux instance

    # Obtain metadata server access credentials. You must specify a validity period and cannot include the X-Forwarded-For header.
TOKEN=`curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds:"`
# Access instance metadata
curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/meta-data/

  • Windows instance

    # Obtain metadata server access credentials. You must specify a validity period and cannot include the X-Forwarded-For header.
$token = Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token-ttl-seconds" = ""} -Method PUT -Uri http://100.100.100.200/latest/api/token
# Access instance metadata
Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token" = $token} -Method GET -Uri http://100.100.100.200/latest/meta-data/

    You must replace the following fields in the preceding code based on your actual needs.

    • : The access credentials are used for authentication to enhance data security. Valid values: 1 to 21600. Unit: seconds.

      • You can repeatedly run the preceding command to access the metadata items of the instance within the validity period of the metadata server access credentials. After the validity period ends, you need to re-obtain the metadata server access credentials. If you do not re-obtain the metadata server access credentials, you cannot access the metadata of the instance.

      • Metadata server access credentials are tied to ECS instances. If you copy the metadata server access credentials of an ECS instance to access another ECS instance, your access is denied.

    • : Replace this field with the specific metadata item that you want to query. For more information, see Instance metadata list.

  • Linux instance

    curl http://100.100.100.200/latest/meta-data/

  • Windows instance (PowerShell)

    Invoke-RestMethod http://100.100.100.200/latest/meta-data/

: Replace this field with the specific metadata item that you want to query. For more information, see Instance metadata list.

Note

If an ECS instance frequently accesses the metadata server to obtain metadata, throttling may occur. We recommend that you cache data such as RAM credentials and refresh the data before it expires.

Configure the security hardening mode as the only access mode for instance metadata

To further enhance security, Alibaba Cloud allows you to configure the security hardening mode as the only access mode for instance metadata. After you configure this setting, requests that use the normal mode are rejected, which helps you defend against most SSRF-related risks that may arise from the normal mode. The following sections describe how to configure this setting in different scenarios.

Configure the security hardening mode as the only access mode when you create an ECS instance

Use the ECS console
Use the API

On the instance purchase page, expand the Advanced Options section and set the metadata access mode to Security hardening mode only.

image

Note

You can select Security Hardening Mode Only on the instance purchase page only if the image that you use supports the security hardening mode for metadata access.

If you cannot select Security hardening mode only when you create an instance in the console, you can create the instance first, upgrade the cloud-init version to 23.2.2 or later, and then configure the security hardening mode as the only access mode for the instance.

Some of the latest public images released by Alibaba Cloud support the security hardening mode for metadata access (the cloud-init version in these images is 23.2.2 or later). You can call the DescribeImages operation to query the ImdsSupport property of an image. If the ImdsSupport property is v2, the image supports the security hardening mode for metadata access.

When you call the RunInstances or CreateInstance operation to create an instance, set the HttpTokens parameter to required. This indicates that the metadata access mode of the instance is Security Hardening Mode Only.

Note

The instance can be started only if the image that you use supports the security hardening mode for metadata access.

If the instance fails to start, you can set the HttpTokens parameter to optional to start the instance, upgrade the cloud-init version to 23.2.2 or later, and then configure the security hardening mode as the only access mode for the instance.

Some of the latest public images released by Alibaba Cloud support the security hardening mode for metadata access (the cloud-init version in these images is 23.2.2 or later). You can call the DescribeImages operation to query the ImdsSupport property of an image. If the ImdsSupport property is v2, the image supports the security hardening mode for metadata access.

Configure the security hardening mode as the only access mode for an existing instance

If you configure the security hardening mode as the only access mode for an ECS instance on which business is deployed, requests that use the normal mode to access metadata are rejected. We recommend that you modify the application code to use the security hardening mode for metadata access and make sure that the ECS instance does not use the normal mode before you configure the security hardening mode as the only access mode for the instance.

Step 1: Modify the application code to use the security hardening mode for metadata access

  1. Identify the instances for which you need to configure the security hardening mode as the only access mode.

    On the Cloud Monitor console Cloud Resources > > Cloud Service Monitoring page, search for ECS Metadata. Identify the ECS instances for which the Monitoring Chart shows that the Number Of Successful Normal Mode Accesses is greater than 0. This indicates that applications on these instances use the normal mode to access the metadata service. You need to configure the security hardening mode as the only access mode for these instances. To ensure data accuracy, we recommend that you set the time range to 14 days or longer.

  2. Make sure that the cloud-init version on the instances that you identified is 23.2.2 or later. If the cloud-init version on an existing ECS instance is not 23.2.2, you can upgrade the cloud-init version to 23.2.2 to support the security hardening mode. For information about how to check and upgrade the cloud-init version, see Install cloud-init.

  3. Modify the application code to first obtain metadata server access credentials and then use the credentials in the request header to obtain metadata. For more information, see Access instance metadata by using the security hardening mode.

  4. Make sure that the code does not use the normal mode.

    On the Cloud Monitor console ECS Metadata page, check whether the Monitoring Chart shows that the Number Of Successful Normal Mode Accesses is No Data (which indicates that the number is 0) for the ECS instances for which you want to configure the security hardening mode as the only access mode. If yes, you can proceed to Step 2. Otherwise, if you configure the security hardening mode as the only access mode for the instances, requests that use the normal mode are rejected, which may affect your business. To ensure data accuracy, we recommend that you set the time range to 14 days or longer.

Step 2: Configure the security hardening mode as the only access mode for instance metadata

Use the ECS console
Use the API

  1. Go to the ECS console - Instances.

  2. In the top navigation bar, select the region and resource group to which the resource belongs. 地域

  3. Find the target instance, go to the instance details page, click All Operations, and search for Modify Instance Metadata Access Information.

  4. Turn on the Enable Instance Metadata Access Channel switch and set Instance Metadata Access Mode to Security Hardening Mode Only.

    image

You can call the DescribeInstances operation to query the HttpTokens parameter (which indicates whether the security hardening mode is required to access instance metadata). Set the parameter to optional to identify the instances whose applications still use the normal mode to access metadata.

Call the ModifyInstanceMetadataOptions operation to modify the metadata access mode of an instance. Set the HttpTokens parameter to required (security hardening mode only).

To avoid business impacts caused by the rejection of requests that use the normal mode after you configure the security hardening mode as the only access mode, you can configure alerts in the Cloud Monitor console to receive notifications when requests that use the normal mode are rejected. If requests that use the normal mode are rejected after you configure the security hardening mode as the only access mode, you need to switch the instance back to the mode that supports both the normal mode and the security hardening mode. Then, make sure that the ECS instance does not use the normal mode before you configure the security hardening mode as the only access mode again.

FAQ

I cannot access instance metadata by using commands in security hardening mode. What do I do?

Check whether the command that you use is correct. The following errors may occur in the command:

  • The validity period of the metadata server access credentials is out of the valid range (1 second to 21,600 seconds)

    curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds: 21700"

  • The request contains the X-Forwarded-For header

    curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-Forwarded-For: www.ba****.com"

  • The specified metadata server access credentials are invalid

    curl -H "X-aliyun-ecs-metadata-token: aaa" -v http://100.100.100.200/latest/meta-data/
Previous: Enable or disable release protection for ECS instancesNext: Use instance identities
  • On this page （1）
  • Instance metadata list
  • Metadata access modes
  • Comparison of access modes
  • Access instance metadata by using different modes
  • Configure the security hardening mode as the only access mode for instance metadata
  • Configure the security hardening mode as the only access mode when you create an ECS instance
  • Configure the security hardening mode as the only access mode for an existing instance
  • FAQ
Feedback