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.
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.
Retrieving Instance Metadata
Because your instance metadata is available from your running instance, you do not need to use the Amazon EC2 console or the AWS CLI. This can be helpful when you're writing scripts to run from your instance. For example, you can access the local IP address of your instance from instance metadata to manage a connection to an external application.
To view all categories of instance metadata from within a running instance, use the following URI:
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:
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:
All instance 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
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.
This example gets the list of available public keys.
This example shows the formats in which public key 0 is available.
This example gets public key 0 (in the OpenSSH key format).
curl http://169.254.169.254/latest/meta-data/public-keys/0/openssh-keyssh-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.
We throttle queries to the instance metadata service on a per-instance basis, and we place limits on the number of simultaneous connections from an instance to the instance metadata service.
If you're using the instance metadata service to retrieve AWS security credentials, avoid querying for credentials during every transaction or concurrently from a high number of threads or processes, as this may lead to throttling. Instead, we recommend that you cache the credentials until they start approaching their expiry time.
If you're throttled while accessing the instance metadata service, retry your query with an exponential backoff strategy.
Configuring Instances with User Data
When you specify user data, note 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 AWS CLI and the Amazon EC2 console perform the base64 encoding for you. The data is decoded before being presented to the instance. For more information about base64 encoding, see http://tools.ietf.org/html/rfc4648.
User data is executed only at launch. If you stop an instance, modify the user data, and start the instance, the new user data is not executed automatically.
To specify user data when you launch an instance
Modify User Data for a Running Instance
You can modify user data for an existing instance. If the instance is running, you must first stop the instance. The new user data is available on your instance after you restart it.
To modify the user data for an Amazon EBS-backed instance
Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.
In the navigation pane, choose Instances, and select the instance.
Click Actions, select Instance State, and then choose Stop.
When you stop an instance, the data on any instance store volumes is erased. Therefore, if you have any data on instance store volumes that you want to keep, be sure to back it up to persistent storage.
In the confirmation dialog box, click Yes, Stop. It can take a few minutes for the instance to stop.
With the instance still selected, choose Actions, select Instance Settings, and then choose View/Change User Data. Note that you can't change the user data if the instance is running, but you can view it.
In the View/Change User Data dialog box, update the user data, and then choose Save.
Retrieving User Data
To retrieve user data, use the following URI:
Requests for user data returns the data as it is (content type
This shows an example of returning comma-separated user data.
curl http://169.254.169.254/latest/user-data1234,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:
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
For more information about dynamic data and examples of how to retrieve it, see Instance Identity Documents.
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 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
replicate-every=1min data defines the first replicant's
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 using the run-instances command, specifying the user data:
aws ec2 run-instances --image-id
ami-12345678--count 4 --instance-type t2.micro --user-data "replicate-every=1min | replicate-every=5min | replicate-every=10min"
After they're launched, all instances have a copy of the user data and the common metadata shown here:
AMI id: ami-12345678
Reservation ID: r-1234567890abcabc0
Public keys: none
Security group name: default
Instance type: t2.micro
However, each instance has certain unique metadata.
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:
She saves the ami-launch-index as a variable:
She saves the user data as a variable:
Finally, Alice uses the 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.
||The AMI ID used to launch the instance.||1.0|
||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|
||The path to the AMI manifest file in Amazon S3. If you used an
Amazon EBS-backed AMI to launch the instance, the returned result is
||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
|The virtual device that contains the root/boot file system.||2007-12-15|
||The virtual devices associated with Amazon EBS volumes, if any are
present. Amazon EBS volumes are only available in metadata if they were
present at launch time or when the instance was last started. The
N indicates the index of the Amazon EBS volume (such
||The virtual devices associated with ephemeral devices, if any are present. The N indicates the index of the ephemeral volume.||2007-12-15|
||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|
||The virtual devices associated with ||2007-12-15|
|The private IPv4 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).||1.0|
||If there is an IAM role associated with the instance, contains information about the last time the instance profile was updated, including the instance's LastUpdated date, InstanceProfileArn, and InstanceProfileId. Otherwise, not present.||2012-01-12|
||If there is an IAM role associated with the instance,
||Notifies the instance that it should reboot in preparation for
bundling. Valid values: ||2008-09-01|
||The ID of this instance.||1.0|
||The type of instance. For more information, see Instance Types.||2007-08-29|
||The ID of the kernel launched with this instance, if applicable.||2008-02-01|
||The private IPv4 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|
||The private IPv4 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|
||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|
||The unique device number associated with that interface. The device
number corresponds to the device name; for example, a
||The private IPv4 addresses that are associated with each
|The IPv6 addresses associated with the interface. Returned only for instances launched into a VPC.||2016-06-30|
||The interface's local hostname.||2011-01-01|
||The private IPv4 addresses associated with the interface.||2011-01-01|
||The instance's MAC address.||2011-01-01|
|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|
||The interface's public DNS (IPv4). If the instance is in a VPC, this category is only
returned if the ||2011-01-01|
||The Elastic IP addresses associated with the interface. There may be multiple IPv4 addresses on an instance.||2011-01-01|
|Security groups to which the network interface belongs. Returned only for instances launched into a VPC.||2011-01-01|
||The 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|
||The ID of the subnet in which the interface resides. Returned only for instances launched into a VPC.||2011-01-01|
||The IPv4 CIDR block of the subnet in which the interface resides. Returned only for instances launched into a VPC.||2011-01-01|
|The IPv6 CIDR block of the subnet in which the interface resides. Returned only for instances launched into a VPC.||2016-06-30|
||The ID of the VPC in which the interface resides. Returned only for instances launched into a VPC.||2011-01-01|
|The IPv4 CIDR block of the VPC in which the interface resides. Returned only for instances launched into a VPC.||2011-01-01|
|The IPv4 CIDR block of the VPC in which the interface resides. Returned only for instances launched into a VPC.||2016-06-30|
|The IPv6 CIDR block of the VPC in which the interface resides. Returned only for instances launched into a VPC.||2016-06-30|
||The Availability Zone in which the instance launched.||2008-02-01|
||Product codes associated with the instance, if any.||2007-03-01|
||The instance's public DNS. If the instance is in a VPC, this category
is only returned if the ||2007-01-19|
||The public IPv4 address. If an Elastic IP address is associated with the instance, the value returned is the Elastic IP address.||2007-01-19|
||Public key. Only available if supplied at instance launch time.||1.0|
||The ID of the RAM disk specified at launch time, if applicable.||2007-10-10|
||The ID of the reservation.||1.0|
The names of the security groups applied to the instance.
After launch, you can only change the security groups of
instances running in a VPC. Such changes are reflected here and in
The domain for AWS resources for the region; for example,
The partition that the resource is in. For standard AWS regions,
the partition is
The approximate time, in UTC, that the operating system for your Spot instance will receive the shutdown signal. This item is present and contains a time value (for example, 2015-01-05T18:02:00Z) only if the Spot instance has been marked for termination by Amazon EC2. The termination-time item is not set to a time if you terminated the Spot instance yourself.
Dynamic Data Categories
The following table lists the categories of dynamic data.
||Value showing whether the customer has enabled detailed
one-minute monitoring in CloudWatch. Valid values: ||2009-04-04|
|JSON containing instance attributes, such as instance-id, private IP address, etc. See Instance Identity Documents.||2009-04-04|
|Used to verify the document's authenticity and content against the signature. See Instance Identity Documents.||2009-04-04|
|Data that can be used by other parties to verify its origin and authenticity. See Instance Identity Documents.||2009-04-04|