All Products
Search
Document Center

Elastic Compute Service:Instance metadata

Last Updated:Apr 28, 2025

Elastic Compute Service (ECS) instance metadata includes attribute information, such as the instance ID, virtual private cloud (VPC), and network interface controller (NIC), which can be accessed from inside the instance by using the metadata service. You can access ECS instance metadata without logging on to the ECS console or call API operations, and use the metadata easily and securely to configure or manage running instances or applications hosted on the instances.

Instance metadata items

You can use the metadata service to obtain the metadata of an ECS instance, including the hostname, instance type, instance name, and image ID. Expand the following table to view instance metadata items.

Click to expand

Metadata item

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 name of the instance.

iZbp1bfqfsvqzxhmnd5****

image-id

The ID of the image 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 multiple NICs are bound to the instance, 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 VPCs support this item.

vpc

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

The ID of the NIC. Replace the [mac] parameter 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 assigned to the NIC.

["192.168.XX.XX"]

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

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

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 assigned to the NIC.

192.168.XX.XX/28

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

The private IPv6 prefix lists assigned to the NIC.

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

disks/

The serial number of the cloud disk.

bp131n0q38u3a4zi****

disks/[disk-serial]/id

The ID of the cloud disk.

d-bp131n0q38u3a4zi****

disks/[disk-serial]/name

The name of the cloud 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

Thisa item is used to obtain the following:

  • The static public IPv4 address of the instance (public IPv4 address that is automatically assigned to the instance)

  • The elastic IPv4 address associated with the primary NIC

120.55.XX.XX

ntp-conf/ntp-servers

The addresses of the Network Time Protocol (NTP) servers.

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 of the instance. This item is available only if a public key was bound to the 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 Yellowdog Updater Modified (YUM) or Advanced Packaging Tool (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 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]

The Resource Access Management (RAM) role of the instance. If a RAM role is attached to the instance, the value of role-name is the RAM role name, and the temporary security credentials of the RAM role are also returned.

The temporary security credentials expire at the time specified by the Expiration field. Call the relevant 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 and release times configured in the operating system of the preemptible instance. The values are in the yyyy-MM-ddThh:mm:ssZ format and displayed in UTC.

2020-04-07T17:03:00Z

instance/virtualization-solution

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

ECS Virt

instance/virtualization-solution-version

The version of the ECS virtualization solution.

2.0

Instance metadata access modes

You can access instance metadata in normal or security hardening mode. For more information, see Access instance metadata in different modes. The following table compares the two modes.

Important

We recommend that you use the security hardening mode. To access metadata in this mode, make sure that the cloud-init version on the instance is 23.2.2 or later. 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

Interaction method

Request-response

Session-oriented

Authentication method

Authenticates requests based on source IP addresses in the same VPC.

Performs authentication based on source IP addresses in the same VPC and instance metadata access credentials.

Instance metadata access credentials have the following characteristics:

  • Short validity period: The credentials are valid for up to 6 hours. Afterward, you must obtain new credentials.

  • Tied to ECS instances. The credentials of one ECS instance cannot be used to access the metadata of another ECS instance.

  • No proxy access support. The credentials are not issued for requests with the X-Forwarded-For header.

Access method

Runs commands to access an endpoint without access credentials.

Obtains instance metadata access credentials for authentication to access an endpoint.

Security level

Low

In normal mode, requests are authenticated based on IP addresses. Attackers can forge the source IP addresses in requests to bypass the IP address-based authentication and launch Server-Side Request Forgery (SSRF) attacks. As a result, instance metadata may be leaked.

High

To access instance metadata, valid metadata access credentials are required for authentication and authorization. These credentials are generated on and tied to ECS instances, and are valid for a limited period, making them difficult for attackers to guess or forge. This helps defend against most SSRF attacks.

Access instance metadata in different modes

Security hardening mode

  • Linux instance

    # Obtain metadata access credentials and specify their validity period. Do not include the X-Forwarded-For header in the request.
    TOKEN=`curl -X PUT "http://100.100.100.200/latest/api/token" -H "X-aliyun-ecs-metadata-token-ttl-seconds:<Validity period of metadata server access credentials>"`
    # Access instance metadata.
    curl -H "X-aliyun-ecs-metadata-token: $TOKEN" http://100.100.100.200/latest/meta-data/<metadata>
  • Windows instance

    # Obtain metadata access credentials and specify their validity period. Do not include the X-Forwarded-For header in the request.
    $token = Invoke-RestMethod -Headers @{"X-aliyun-ecs-metadata-token-ttl-seconds" = "<Validity period of metadata server access credentials>"} -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/<metadata>

    Replace the following fields in the preceding code with actual values:

    • <Validity period of metadata server access credentials>: the validity period of the metadata access credentials. Valid values: 1 to 21600. Unit: seconds.

      • Within the validity period, you can repeatedly run commands to access the instance metadata by using the metadata access credentials. After the credentials expire, you must obtain new credentials to access the metadata.

      • Metadata access credentials are tied to ECS instances. You cannot use the credential of one ECS instance to access the metadata of another ECS instance.

    • <metadata>: the metadata item you want to query. For more information, see Instance metadata items.

Normal mode

  • Linux instance

    curl http://100.100.100.200/latest/meta-data/<metadata>
  • Windows instance (PowerShell)

    Invoke-RestMethod http://100.100.100.200/latest/meta-data/<metadata>

<metadata>: the metadata item you want to query. For more information, see Instance metadata items.

Note

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

Configure the security hardening mode as the exclusive metadata access mode for an instance

To enhance security, Alibaba Cloud allows you to configure the security hardening mode as the exclusive metadata access mode for an instance. Once this setting is configured, requests that use the normal mode are rejected. This helps defend against most SSRF-related risks. The following sections describe how to configure this setting in different scenarios.

Important

If you use the credentials tool to obtain the temporary identity credentials of the RAM role attached to an ECS instance, switching to the security hardening mode may affect your business. To prevent this issue, upgrade the credentials tool. For information about the versions that support the security hardening mode, see Obtain temporary access credentials by using the credentials tool.

Configure the security hardening mode as the exclusive metadata access mode during instance creation

Use the ECS console

On the instance buy page, expand the Advanced Options section and set the Metadata Access Mode parameter to Security Hardening Mode.

image

Note

You can select Security Hardening Mode only if the image that you use supports it.

If you cannot select Security Hardening Mode, create the instance, upgrade the cloud-init version to 23.2.2 or later, and then configure the security hardening mode as the exclusive metadata access mode for the instance.

Some latest Alibaba Cloud public images support the security hardening mode because they are pre-installed with cloud-init 23.2.2 or later. To check whether an image supports the mode, call the DescribeImages operation and view the ImdsSupport value for the image in the response. If the ImdsSupport value is v2, the image supports the security hardening mode.

Call an API operation

When you call the RunInstances or CreateInstance operation to create an ECS instance, set the HttpTokens parameter to required to enable Security Hardening Mode.

Note

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

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

Some latest Alibaba Cloud public images support the security hardening mode because they are pre-installed with cloud-init version 23.2.2 or later. To check whether an image supports the mode, call the DescribeImages operation and view the ImdsSupport value for the image in the response. If the value of ImdsSupport is v2, the image supports the security hardening mode.

Configure the security hardening mode as the exclusive metadata access mode for an existing instance

If you no longer use the normal mode to access the metadata of an existing ECS instance, modify the application code of the instance and configure the security hardening mode as the exclusive metadata access mode. After this setting is configured, requests that use the normal mode are rejected.

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

  1. Identify the instances whose application code you want to modify.

    • Method 1: Log on to the CloudMonitor console. On the Cloud Resource Monitoring > Cloud Service Monitoring page, search for ECS Metadata. Identify the ECS instances whose Monitoring Charts show that the number of successful accesses in normal mode(count) is greater than 0, which means that the applications on the instances use the normal mode. You must configure the security hardening mode for these instances. To ensure data accuracy, we recommend a time range of 14 days or longer.

    • Method 2: Use the ACS-ECS-ImdsPacketAnalyzer plug-in provided by Cloud Assistant to identify the processes on an ECS instance that use the normal mode.

      The plug-in is available only for Linux operating systems because Cloud Assistant Agent is pre-installed on Linux instances during instance creation. However, operating system restrictions apply.

      Supported operating systems and usage procedure

      Deploying the ACS-ECS-ImdsPacketAnalyzer plug-in on an instance may affect the instance performance.

      Supported following operating systems:

      • Alibaba Cloud Linux 3

      • Anolis OS 8

      • CentOS Stream 8 and 9

      • CentOS 8

      • Ubuntu 20 and 24

      • Debian 10, 11, and 12

      • Fedora 35 and later

      • AlmaLinux 8 and 9

      • Rocky Linux 8 and 9

      • Red Hat Enterprise Linux 8 and 9

      • For Red Hat, you must download and install the RPM package of Cloud Assistant Agent. For more information, see Install Cloud Assistant Agent.

      • SUSE 15.1, 15.2, 15.3, 15.4, 15.5, and 15.6

      • openSUSE 15.2, 15.3, 15.4, 15.5, and 15.6

      Procedure:

      1. Connect to an ECS instance. For more information, see Methods for connecting to an ECS instance.

      2. Run the following command to check whether Cloud Assistant Agent is installed on the instance and provides the ACS-ECS-ImdsPacketAnalyzer plug-in:

        sudo acs-plugin-manager --list

        p940997

      3. Run the following command to deploy the imds_tracer_tool service:

        sudo acs-plugin-manager --exec --plugin ACS-ECS-ImdsPacketAnalyzer

        The following output shows that the service is deployed.

        image.png

      4. Run the following command to check the deployment status of the imds_tracer_tool service:

        sudo systemctl status imds_tracer_tool

        p940998

      5. Run the following command to display all applications that support the normal and security hardening modes:

        cat /var/log/imds/imds-trace.* | grep WARNING

        p940995

  2. Make sure that the cloud-init version on the identified instances is 23.2.2 or later. If the cloud-init version is earlier than 23.2.2, upgrade to version 23.2.2 or later. For information about how to check and upgrade the version, see Install cloud-init.

  3. Modify your application code to obtain metadata access credentials and then include the credentials in the request header to access instance metadata. For more information, see Access instance metadata in security hardening mode.

  4. Make sure that your application code no longer uses the normal mode to access instance metadata.

    On ECS Metadata page in the CloudMonitor console , check whether the Monitoring Charts of the identified instances show the number of successful accesses in normal mode(count) as No data. If yes, you can proceed to Step 2. If not, requests to access instance metadata in normal mode may be rejected after you configure the security hardening mode as the exclusive metadata access mode for the instances. To ensure data accuracy, we recommend a time range of 14 days or longer.

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

Use the ECS console

  1. Go to ECS console - Instance.

  2. In the top navigation bar, select the region and resource group of the resource that you want to manage. 地域

  3. Find the instance that you want to manage, click the ID of the instance to go to the instance details page, and then click All Actions in the upper-right corner. In the pane that appears, search for and click Modify Instance Metadata Access Information.

  4. Turn on Enable Access Channel for Instance Metadata and set Instance Metadata Access Mode to Security Hardening Mode.

    image

Call an API operation

You can call the DescribeInstances operation and view the HttpTokens value in the response to check whether the security hardening mode is forcefully used to access instance metadata. Applications on ECS instances whose HttpTokens value is optional still use the normal mode. Identify these ECS instances in the DescribeInstances response.

Call the ModifyInstanceMetadataOptions operation with HttpTokens set to required for each instance to change the metadata access mode to the security hardening mode.

After you configure the security hardening mode as the only metadata access mode for ECS instances, requests to access metadata in normal mode are rejected. To avoid business interruptions due to request failure, configure alerts in the CloudMonitor console to be notified 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 exclusive metadata access mode, configure the instance to support the normal and security hardening modes, make sure that the instance metadata is no longer accessed in normal mode, and then reconfigure the security hardening mode as the exclusive metadata access mode for the instance.

FAQ

What do I do if I cannot run a command to access instance metadata in security hardening mode?

Check whether the command is correct. Common issues include:

  • The validity period of the metadata access credentials is not within the range of 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 includes 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 access credentials are invalid.

    curl -H "X-aliyun-ecs-metadata-token: aaa" -v http://100.100.100.200/latest/meta-data/