| « PreviousNext » | |
   | Did this page help you? Yes | No | Tell us about it... |
Instance Metadata and User Data
Topics
Instance metadata is data about your EC2 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 EC2 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 from an AMI. 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 Attributes of 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.
For more information about retrieving instance metadata and dynamic data, see Retrieving Instance Metadata. For more information about retrieving user data, see Retrieving User Data
Note
You are not billed for HTTP requests used to retrieve instance metadata and user data.
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/
On a Linux instance, you can use a tool such as cURL, or use the GET command, for example:
PROMPT> 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
On a Windows instance, you can install a tool such as GNU Wget or cURL to retrieve instance metadata at the command line, or you can copy and paste the URI into a browser. If you do not want to install any third-party tools, you can use PowerShell cmdlets to retrieve the URI. For example, if you are running version 3.0 or later of PowerShell, use the following cmdlet:
PROMPT> invoke-restmethod -uri http://169.254.169.254/latest/meta-data/
Note
If you do install a third-party tool on a Windows instance, ensure that you read the accompanying documentation carefully, as the method of calling the HTTP and the output format might be different from what is documented here.
To retrieve dynamic data from within a running instance, use the following URI:
http://169.254.169.254/latest/dynamic/
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
The following are examples of requests and responses on a Linux instance.
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.
PROMPT> GET 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 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.
PROMPT> GET 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
These examples get the value of some of the metadata items from the preceding example.
PROMPT> GET http://169.254.169.254/latest/meta-data/ami-id ami-2bb65342
PROMPT> GET http://169.254.169.254/latest/meta-data/reservation-id r-fea54097
PROMPT> GET http://169.254.169.254/latest/meta-data/hostname ec2-67-202-51-223.compute-1.amazonaws.com
This example gets the list of available public keys.
PROMPT> GET 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.
PROMPT> GET http://169.254.169.254/latest/meta-data/public-keys/0/ openssh-key
This example gets public key 0 (in the OpenSSH key format).
PROMPT> GET 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.
PROMPT> GET 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 EC2 instance launched into a VPC.
PROMPT> GET 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.
PROMPT> GET 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.
PROMPT> GET http://169.254.169.254/latest/user-data [general] instances: 4 [instance-0] s3-bucket: <user_name> [instance-1] reboot-on-error: yes
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:
PROMPT> 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 ebsAfter 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
| Metadata | Value |
|---|---|
| instance-id | i-10a64379 |
| ami-launch-index | 0 |
| public-hostname | ec2-67-202-51-223.compute-1.amazonaws.com |
| public-ipv4 | 67.202.51.223 |
| local-hostname | ip-10-251-50-35.ec2.internal |
| local-ipv4 | 10.251.50.35 |
Instance 2
| Metadata | Value |
|---|---|
| instance-id | i-10a64380 |
| ami-launch-index | 1 |
| public-hostname | ec2-67-202-51-224.compute-1.amazonaws.com |
| public-ipv4 | 67.202.51.224 |
| local-hostname | ip-10-251-50-36.ec2.internal |
| local-ipv4 | 10.251.50.36 |
Instance 3
| Metadata | Value |
|---|---|
| instance-id | i-10a64381 |
| ami-launch-index | 2 |
| public-hostname | ec2-67-202-51-225.compute-1.amazonaws.com |
| public-ipv4 | 67.202.51.225 |
| local-hostname | ip-10-251-50-37.ec2.internal |
| local-ipv4 | 10.251.50.37 |
Instance 4
| Metadata | Value |
|---|---|
| instance-id | i-10a64382 |
| ami-launch-index | 3 |
| public-hostname | ec2-67-202-51-226.compute-1.amazonaws.com |
| public-ipv4 | 67.202.51.226 |
| local-hostname | ip-10-251-50-38.ec2.internal |
| local-ipv4 | 10.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.
She connects to one of the instances, and retrieves the ami-launch-index for that instance to ensure it is one of the replicants:
PROMPT> GET http://169.254.169.254/latest/meta-data/ami-launch-index 2
She saves the ami-launch-index as a variable:
PROMPT> ami_launch_index=`GET http://169.254.169.254/latest/meta-data/ami-launch-index`
She saves the user data as a variable:
PROMPT> user_data=`GET http://169.254.169.254/latest/user-data/`
Finally, Alice runs a Linux cut command to extract the portion of the user data that is applicable to that instance:
PROMPT> echo $user_data | cut -d"|" -f"$ami_launch_index" replicate-every=5min
Instance Metadata Categories
The following table lists the categories of instance metadata.
| Data | Description | Version 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
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 |
hostname | The 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-06-01 |
iam/security-credentials/
| 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-06-01 |
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 Families and 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/
| 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/
| The private IPv4 addresses that are associated with each
public-ip address and assigned to that
interface. | 2011-01-01 |
network/interfaces/macs/
| The interface's local hostname. | 2011-01-01 |
network/interfaces/macs/
| The private IP addresses associated with the interface. | 2011-01-01 |
network/interfaces/macs/
| The instance's media access control (MAC) address. | 2011-01-01 |
network/interfaces/macs/
| 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/
| The interface's public hostname. Not returned for EC2 instances launched into a VPC. | 2011-01-01 |
network/interfaces/macs/
| The elastic IP addresses associated with the interface. There may be multiple IP addresses on an instance. | 2011-01-01 |
network/interfaces/macs/
| Security groups to which the network interface belongs. Returned only for EC2 instances launched into a VPC. | 2011-01-01 |
network/interfaces/macs/
| IDs of the security groups to which the network interface belongs. Returned only for EC2 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/
| The ID of the subnet in which the interface resides. Returned only for EC2 instances launched into a VPC. | 2011-01-01 |
network/interfaces/macs/
| The CIDR block of the subnet in which the interface resides. Returned only for EC2 instances launched into a VPC. | 2011-01-01 |
network/interfaces/macs/
| The ID of the VPC in which the interface resides. Returned only for EC2 instances launched into a VPC. | 2011-01-01 |
network/interfaces/macs/
| The CIDR block of the VPC in which the interface resides. Returned only for EC2 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 public hostname of the instance. Not returned for EC2 instances launched into a VPC. For more information, see Elastic IP Addresses (EIP). | 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 EC2 instances launched into a VPC can change security
groups after launch. These changes will be reflected here and in
network/interfaces/macs/ | 1.0 |
Dynamic Data Categories
The following table lists the categories of dynamic data.
| Data | Description | Version introduced |
|---|---|---|
fws/instance-monitoring
| Value showing whether the customer has enabled detailed
one-minute monitoring in CloudWatch. Valid values: enabled |
disabled | 2009-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 |
