Amazon Elastic Compute Cloud
User Guide for Linux (API Version 2014-10-01)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

Instance Metadata and User Data

Instance metadata is data about your instance that you can use to configure or manage the running instance. Instance metadata is divided into categories. For more information, see Instance Metadata Categories.

EC2 instances can also include dynamic data, such as an instance identity document that is generated when the instance is launched. For more information, see Dynamic Data Categories.

You can also access the user data that you supplied when launching your instance. For example, you can specify parameters for configuring your instance, or attach a simple script. You can also use this data to build more generic AMIs that can be modified by configuration files supplied at launch time. For example, if you run web servers for various small businesses, they can all use the same AMI and retrieve their content from the Amazon S3 bucket you specify in the user data at launch. To add a new customer at any time, simply create a bucket for the customer, add their content, and launch your AMI. If you launch more than one instance at the same time, the user data is available to all instances in that reservation.

Because you can access instance metadata and user data from within your running instance, you do not need to use the Amazon EC2 console or the CLI tools. This can be helpful when you're writing scripts to run from within your instance. For example, you can access your instance's local IP address from within the running instance to manage a connection to an external application.

Important

Although you can only access instance metadata and user data from within the instance itself, the data is not protected by cryptographic methods. Anyone who can access the instance can view its metadata. Therefore, you should take suitable precautions to protect sensitive data (such as long-lived encryption keys). You should not store sensitive data, such as passwords, as user data.

For more information about adding user data when you launch an instance, see Launching an Instance. You can add or modify user data on Amazon EBS-backed instances when they're stopped. For more information about adding user data to a stopped instance, see Modifying a Stopped Instance.

When you are adding user data, take note of the following:

  • User data is treated as opaque data: what you give is what you get back. It is up to the instance to be able to interpret it.

  • User data is limited to 16 KB. This limit applies to the data in raw form, not base64-encoded form.

  • User data must be base64-encoded before being submitted to the API. The API command line tools perform the base64 encoding for you. The data is decoded before being presented to the instance. For more information about base64 encodings, go to http://tools.ietf.org/html/rfc4648.

Retrieving Instance Metadata

To view all categories of instance metadata from within a running instance, use the following URI:

http://169.254.169.254/latest/meta-data/

Note that you are not billed for HTTP requests used to retrieve instance metadata and user data.

You can use a tool such as cURL, or if your instance supports it, the GET command; for example:

$ curl http://169.254.169.254/latest/meta-data/
$ GET http://169.254.169.254/latest/meta-data/

You can also download the Instance Metadata Query tool, which allows you to query the instance metadata without having to type out the full URI or category names:

http://aws.amazon.com/code/1825

All metadata is returned as text (content type text/plain). A request for a specific metadata resource returns the appropriate value, or a 404 - Not Found HTTP error code if the resource is not available.

A request for a general metadata resource (the URI ends with a /) returns a list of available resources, or a 404 - Not Found HTTP error code if there is no such resource. The list items are on separate lines, terminated by line feeds (ASCII 10).

Examples of Retrieving Instance Metadata

This example gets the available versions of the instance metadata. These versions do not necessarily correlate with an Amazon EC2 API version. The earlier versions are available to you in case you have scripts that rely on the structure and information present in a previous version.

$ curl http://169.254.169.254/
1.0
2007-01-19
2007-03-01
2007-08-29
2007-10-10
2007-12-15
2008-02-01
2008-09-01
2009-04-04
2011-01-01
2011-05-01
2012-01-12
2014-02-25
latest

This example gets the top-level metadata items. Some items are only available for instances in a VPC. For more information about each of these items, see Instance Metadata Categories.

$ curl http://169.254.169.254/latest/meta-data/    
ami-id
ami-launch-index
ami-manifest-path
block-device-mapping/
hostname
instance-action
instance-id
instance-type
kernel-id
local-hostname
local-ipv4
mac
network/
placement/
public-hostname
public-ipv4
public-keys/
reservation-id
security-groups
services/

These examples get the value of some of the metadata items from the preceding example.

$ curl http://169.254.169.254/latest/meta-data/ami-id
ami-2bb65342
$ curl http://169.254.169.254/latest/meta-data/reservation-id
r-fea54097
$ curl http://169.254.169.254/latest/meta-data/hostname
ec2-203-0-113-25.compute-1.amazonaws.com

This example gets the list of available public keys.

$ curl http://169.254.169.254/latest/meta-data/public-keys/
0=my-public-key

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

$ curl http://169.254.169.254/latest/meta-data/public-keys/0
openssh-key

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

$ curl 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

This example shows the information available for a specific network interface (indicated by the MAC address) on an NAT instance in the EC2-Classic platform.

$ curl http://169.254.169.254/latest/meta-data/network/interfaces/macs/02:29:96:8f:6a:2d/
device-number
local-hostname
local-ipv4s
mac
owner-id
public-hostname
public-ipv4s

This example gets the subnet ID for an instance launched into a VPC.

$ curl http://169.254.169.254/latest/meta-data/network/interfaces/macs/02:29:96:8f:6a:2d/subnet-id
subnet-be9b61d7

Retrieving User Data

To retrieve user data, use the following URI:

http://169.254.169.254/latest/user-data

Requests for user data returns the data as it is (content type application/x-octetstream).

This shows an example of returning comma-separated user data.

$ curl http://169.254.169.254/latest/user-data
1234,john,reboot,true | 4512,richard, | 173,,,

This shows an example of returning line-separated user data.

$ curl http://169.254.169.254/latest/user-data
[general]
instances: 4

[instance-0]
s3-bucket: <user_name>

[instance-1]
reboot-on-error: yes

Retrieving Dynamic Data

To retrieve dynamic data from within a running instance, use the following URI:

http://169.254.169.254/latest/dynamic/

This example shows how to retrieve the high-level instance identity categories:

$ curl http://169.254.169.254//latest/dynamic/instance-identity/
pkcs7
signature
document

Example: AMI Launch Index Value

This example demonstrates how you can use both user data and instance metadata to configure your instances.

Alice wants to launch four instances of her favorite Linux database AMI, with the first acting as master and the remaining three acting as replicas. When she launches them, she wants to add user data about the replication strategy for each replicant. She is aware that this data will be available to all four instances, so she needs to structure the user data in a way that allows each instance to recognize which parts are applicable to it. She can do this using the ami-launch-index instance metadata value, which will be unique for each instance.

Here is the user data that Alice has constructed:

replicate-every=1min | replicate-every=5min | replicate-every=10min

The replicate-every=1min data defines the first replicant's configuration, replicate-every=5min defines the second replicant's configuration, and so on. Alice decides to provide this data as an ASCII string with a pipe symbol (|) delimiting the data for the separate instances.

Alice launches four instances, specifying the user data:

$ ec2-run-instances ami-2bb65342 -n 4 -d "replicate-every=1min | replicate-every=5min | replicate-every=10min"

RESERVATION     r-fea54097      598916040194    default
INSTANCE i-10a64379  ami-2bb65342	pending	0	m1.small	2010-03-19T13:59:03+0000	us-east-1a	aki-94c527fd	ari-96c527ff	monitoring-disabled		ebs
INSTANCE i-10a64380  ami-2bb65342	pending	0	m1.small	2010-03-19T13:59:03+0000	us-east-1a	aki-94c527fd	ari-96c527ff	monitoring-disabled		ebs
INSTANCE i-10a64381  ami-2bb65342	pending	0	m1.small	2010-03-19T13:59:03+0000	us-east-1a	aki-94c527fd	ari-96c527ff	monitoring-disabled		ebs
INSTANCE i-10a64382  ami-2bb65342	pending	0	m1.small	2010-03-19T13:59:03+0000	us-east-1a	aki-94c527fd	ari-96c527ff	monitoring-disabled		ebs

After they're launched, all instances have a copy of the user data and the common metadata shown here:

  • AMI id: ami-2bb65342

  • Reservation ID: r-fea54097

  • Public keys: none

  • Security group name: default

  • Instance type: m1.small

However, each instance has certain unique metadata.

Instance 1

MetadataValue
instance-idi-10a64379
ami-launch-index0
public-hostnameec2-203-0-113-25.compute-1.amazonaws.com
public-ipv467.202.51.223
local-hostnameip-10-251-50-12.ec2.internal
local-ipv410.251.50.35

Instance 2

MetadataValue
instance-idi-10a64380
ami-launch-index1
public-hostnameec2-67-202-51-224.compute-1.amazonaws.com
public-ipv467.202.51.224
local-hostnameip-10-251-50-36.ec2.internal
local-ipv410.251.50.36

Instance 3

MetadataValue
instance-idi-10a64381
ami-launch-index2
public-hostnameec2-67-202-51-225.compute-1.amazonaws.com
public-ipv467.202.51.225
local-hostnameip-10-251-50-37.ec2.internal
local-ipv410.251.50.37

Instance 4

MetadataValue
instance-idi-10a64382
ami-launch-index3
public-hostnameec2-67-202-51-226.compute-1.amazonaws.com
public-ipv467.202.51.226
local-hostnameip-10-251-50-38.ec2.internal
local-ipv410.251.50.38

Alice can use the ami-launch-index value to determine which portion of the user data is applicable to a particular instance.

  1. She connects to one of the instances, and retrieves the ami-launch-index for that instance to ensure it is one of the replicants:

    $ curl http://169.254.169.254/latest/meta-data/ami-launch-index
    2
  2. She saves the ami-launch-index as a variable:

    $ ami_launch_index=`curl http://169.254.169.254/latest/meta-data/ami-launch-index`
  3. She saves the user data as a variable:

    $ user_data=`curl http://169.254.169.254/latest/user-data/`
  4. Finally, Alice runs a Linux cut command to extract the portion of the user data that is applicable to that instance:

    $ echo $user_data | cut -d"|" -f"$ami_launch_index"
    replicate-every=5min

Instance Metadata Categories

The following table lists the categories of instance metadata.

DataDescriptionVersion Introduced
ami-id The AMI ID used to launch the instance.1.0
ami-launch-index If you started more than one instance at the same time, this value indicates the order in which the instance was launched. The value of the first instance launched is 0.1.0
ami-manifest-path The path to the AMI's manifest file in Amazon S3. If you used an Amazon EBS-backed AMI to launch the instance, the returned result is unknown.1.0
ancestor-ami-ids The AMI IDs of any instances that were rebundled to create this AMI. This value will only exist if the AMI manifest file contained an ancestor-amis key.2007-10-10
block-device-mapping/ami The virtual device that contains the root/boot file system.2007-12-15
block-device-mapping/ebsN The virtual devices associated with Amazon EBS volumes, if any are present. This value is only available in metadata if it is present at launch time. The N indicates the index of the Amazon EBS volume (such as ebs1 or ebs2).2007-12-15
block-device-mapping/ephemeralN The virtual devices associated with ephemeral devices, if any are present. The N indicates the index of the ephemeral volume.2007-12-15
block-device-mapping/root The virtual devices or partitions associated with the root devices, or partitions on the virtual device, where the root (/ or C:) file system is associated with the given instance.2007-12-15
block-device-mapping/swap The virtual devices associated with swap. Not always present.2007-12-15
hostnameThe private hostname of the instance. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0).1.0
iam/info Returns information about the last time the instance profile was updated, including the instance's LastUpdated date, InstanceProfileArn, and InstanceProfileId.2012-01-12
iam/security-credentials/role-name Where role-name is the name of the IAM role associated with the instance. Returns the temporary security credentials (AccessKeyId, SecretAccessKey, SessionToken, and Expiration) associated with the IAM role.2012-01-12
instance-action Notifies the instance that it should reboot in preparation for bundling. Valid values: none | shutdown | bundle-pending.2008-09-01
instance-id The ID of this instance.1.0
instance-type The type of instance. For more information, see Instance Types.2007-08-29
kernel-id The ID of the kernel launched with this instance, if applicable.2008-02-01
local-hostname The private DNS hostname of the instance. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0).2007-01-19
local-ipv4 The private IP address of the instance. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0).1.0
mac The instance's media access control (MAC) address. In cases where multiple network interfaces are present, this refers to the eth0 device (the device for which the device number is 0).2011-01-01
network/interfaces/macs/mac/device-number The device number associated with that interface. Each interface must have a unique device number. The device number serves as a hint to device naming in the instance; for example, device-number is 2 for the eth2 device.2011-01-01
network/interfaces/macs/mac/ipv4-associations/public-ip The private IPv4 addresses that are associated with each public-ip address and assigned to that interface.2011-01-01
network/interfaces/macs/mac/local-hostname The interface's local hostname.2011-01-01
network/interfaces/macs/mac/local-ipv4s The private IP addresses associated with the interface. 2011-01-01
network/interfaces/macs/mac/mac The instance's MAC address.2011-01-01
network/interfaces/macs/mac/owner-id The ID of the owner of the network interface. In multiple-interface environments, an interface can be attached by a third party, such as Elastic Load Balancing. Traffic on an interface is always billed to the interface owner.2011-01-01
network/interfaces/macs/mac/public-hostname The interface's public DNS. If the instance is in a VPC, this category is only returned if the enableDnsHostnames attribute is set to true. For more information, see Using DNS with Your VPC.2011-01-01
network/interfaces/macs/mac/public-ipv4s The Elastic IP addresses associated with the interface. There may be multiple IP addresses on an instance. 2011-01-01
network/interfaces/macs/mac/security-groups Security groups to which the network interface belongs. Returned only for instances launched into a VPC. 2011-01-01
network/interfaces/macs/mac/security-group-ids IDs of the security groups to which the network interface belongs. Returned only for instances launched into a VPC. For more information on security groups in the EC2-VPC platform, see Security Groups for Your VPC.2011-01-01
network/interfaces/macs/mac/subnet-id The ID of the subnet in which the interface resides. Returned only for instances launched into a VPC. 2011-01-01
network/interfaces/macs/mac/subnet-ipv4-cidr-block The CIDR block of the subnet in which the interface resides. Returned only for instances launched into a VPC. 2011-01-01
network/interfaces/macs/mac/vpc-id The ID of the VPC in which the interface resides. Returned only for instances launched into a VPC. 2011-01-01
network/interfaces/macs/mac/vpc-ipv4-cidr-block The CIDR block of the VPC in which the interface resides. Returned only for instances launched into a VPC. 2011-01-01
placement/availability-zone The Availability Zone in which the instance launched.2008-02-01
product-codes Product codes associated with the instance, if any. 2007-03-01
public-hostname The instance's public DNS. If the instance is in a VPC, this category is only returned if the enableDnsHostnames attribute is set to true. For more information, see Using DNS with Your VPC.2007-01-19
public-ipv4 The public IP address. If an Elastic IP address is associated with the instance, the value returned is the Elastic IP address.2007-01-19
public-keys/0/openssh-key Public key. Only available if supplied at instance launch time.1.0
ramdisk-id The ID of the RAM disk specified at launch time, if applicable.2007-10-10
reservation-id ID of the reservation.1.0
security-groups

The names of the security groups applied to the instance.

Note

Only instances launched into a VPC can change security groups after launch. These changes will be reflected here and in network/interfaces/macs/mac/security-groups.

1.0
services/domain

The domain for AWS resources for the region; for example, amazonaws.com for us-east-1.

2014-02-25

Dynamic Data Categories

The following table lists the categories of dynamic data.

DataDescriptionVersion introduced
fws/instance-monitoring Value showing whether the customer has enabled detailed one-minute monitoring in CloudWatch. Valid values: enabled | disabled2009-04-04
instance-identity/document JSON containing instance attributes, such as instance-id, private IP address, etc. 2009-04-04
instance-identity/pkcs7 Used to verify the document's authenticity and content against the signature. 2009-04-04
instance-identity/signature Data that can be used by other parties to verify its origin and authenticity. 2009-04-04