Menu
Amazon Elastic Compute Cloud
User Guide for Windows Instances

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.

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.

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:

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 PowerShell cmdlets to retrieve the URI. For example, if you are running version 3.0 or later of PowerShell, use the following cmdlet:

Copy
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/

If you don't want to use PowerShell, you can install a third-party tool such as GNU Wget or cURL.

Important

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.

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 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.

Copy
PS C:\> Invoke-RestMethod -uri 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 2014-11-05 2015-10-20 2016-04-19 2016-06-30 2016-09-02 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.

Copy
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/ ami-id ami-launch-index ami-manifest-path block-device-mapping/ hostname iam/ instance-action instance-id instance-type local-hostname local-ipv4 mac metrics/ network/ placement/ profile 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.

Copy
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/ami-id ami-12345678
Copy
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/reservation-id r-fea54097
Copy
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/local-hostname ip-10-251-50-12.ec2.internal
Copy
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/public-hostname ec2-203-0-113-25.compute-1.amazonaws.com

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.

Copy
PS C:\> Invoke-RestMethod -uri 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.

Copy
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/meta-data/network/interfaces/macs/02:29:96:8f:6a:2d/subnet-id subnet-be9b61d7

Throttling

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.

Executing Scripts with User Data

You can specify scripts to execute when an instance starts. You enter the script in the User data section of the Launch Instance Wizard. The User data option is located on the Step 3: Configure Instance Details page in the Advanced Details section. The example in the following image changes the name of the instance to Server2012R2Test when the instance booted. The Amazon EC2 console performs base64 encoding for you.

For EC2Config or EC2Launch to execute user data scripts, you must enclose the lines of the specified script within one of the following special tags:

<script></script>

Run any command that you can run in a Command Prompt window.

Example: <script>dir > c:\test.log</script>

<powershell></powershell>

Run any command that you can run at the Windows PowerShell command prompt.

If you use an AMI that includes the AWS Tools for Windows PowerShell, you can also use those cmdlets. If an IAM role is associated with your instance, then you don't need to specify credentials to the cmdlets, as applications that run on the instance can use the role's credentials to access AWS resources such as Amazon S3 buckets.

Example: <powershell>Read-S3Object -BucketName myS3Bucket -Key myFolder/myFile.zip -File c:\destinationFile.zip</powershell>

You can separate the commands in a script using line breaks.

If both script and powershell tags are present, the batch script are run first and the PowerShell script next, regardless of the order in which they appear.

The \Log (EC2Launch) or \Logs (EC2Config) folder contains output from the standard output and standard error streams.

If you're using the Amazon EC2 API or a tool that does not perform base64 encoding of the user data, you must encode the user data yourself. If not, an error is logged about being unable to find script or powershell tags to execute. The following is an example that sets the encoding using PowerShell.

Copy
$UserData = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($Script))

Initial Boot

By default, all Amazon AMIs have user data execution enabled for the initial boot. For instances using the EC2Config service, you can specify that user data must be executed on the next boot or restart of the service. For more information, see Ec2 Service Properties.

User data script execution happens under the local administrator user only when a random password is generated. The EC2Config service generates the password and is aware of the credentials briefly (prior to sending to the console). EC2Config doesn't store or track password changes, so when you don't generate a random password, user data execution is performed by the EC2Config service account. If you choose the option to Shutdown with Sysprep in EC2Config, user data script execution is enabled, regardless of the setting of the User Data check box.

Similarly, for instances using the EC2Launch service, if you choose the option to Shutdown with Sysprep, user data script execution is enabled when the instance is restarted.

Subsequent Boots

Because Amazon AMIs automatically disable user data script execution after the initial boot, you can do one of the following to make user data persist across reboots:

  • For EC2Config, specify that user data must be executed on the next boot or restart of the service. For more information, see Ec2 Service Properties. You can also use this option if you want to add or change user data for an existing instance.

  • For EC2Config, programmatically create a scheduled task to run at system start using schtasks.exe /Create, and point the scheduled task to the user data script (or another script) at C:\Program Files\Amazon\Ec2ConfigService\Scripts\UserScript.ps1.

  • For EC2Config, programmatically enable the user data plug-in in Config.xml using a script similar to the following:

    Copy
    <powershell> $EC2SettingsFile="C:\Program Files\Amazon\Ec2ConfigService\Settings\Config.xml" $xml = [xml](get-content $EC2SettingsFile) $xmlElement = $xml.get_DocumentElement() $xmlElementToModify = $xmlElement.Plugins foreach ($element in $xmlElementToModify.Plugin) { if ($element.name -eq "Ec2SetPassword") { $element.State="Enabled" } elseif ($element.name -eq "Ec2HandleUserData") { $element.State="Enabled" } } $xml.Save($EC2SettingsFile) </powershell>
  • For EC2Config version 2.1.10 and later, or for EC2Launch, you can use <persist>true</persist> in the user data to enable the plug-in after user data execution.

    Copy
    <powershell> insert script here </powershell> <persist>true</persist>

Overriding the Initialize Drives Setting with User Data

Use the following to override the initialize drives setting with user data. These settings will be used every time you reboot the instance.

Copy
<InitializeDrivesSettings> <SettingsGroup>FormatWithTRIM</SettingsGroup> </InitializeDrivesSettings>

Use a settings group to specify how you want to initialize drives.

Important

In EC2Config version 3.18 or later, the TRIM command is disabled for the duration of the disk format operation, by default. This change improves formatting times in Windows. To enable TRIM for the duration of the disk format operation, specify FormatWithTRIM for EC2Config version 3.18 or later. FormatWithoutTRIM is still available for earlier versions of EC2Config. Use FormatWithoutTRIM to disable TRIM.

  • FormatWithTRIM (v3.18 and above): This setting enables the TRIM command when formatting drives. After a drive has been formatted and initialized, the system restores TRIM configuration.

  • FormatWithoutTRIM: This setting disables the TRIM command when formatting drives and improves formatting times in Windows. After a drive has been formatted and initialized, the system restores TRIM configuration.

  • DisableInitializeDrives: This setting disables formatting for new drives. Use this setting to initialize drives manually.

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

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, choose Instances, and select the instance.

  3. Click Actions, select Instance State, and then choose Stop.

    Warning

    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.

  4. In the confirmation dialog box, click Yes, Stop. It can take a few minutes for the instance to stop.

  5. 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.

  6. 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:

http://169.254.169.254/latest/user-data

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

This example returns comma-separated user data.

Copy
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/user-data 1234,john,reboot,true | 4512,richard, | 173,,,

This example returns line-separated user data.

Copy
PS C:\> Invoke-RestMethod -uri 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:

Copy
PS C:\> Invoke-RestMethod -uri http://169.254.169.254/latest/dynamic/instance-identity/ document rsa2048 pkcs7 signature

For more information about dynamic data and examples of how to retrieve it, see Instance Identity Documents.

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 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. 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 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 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
iam/info 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
iam/security-credentials/role-name If there is an IAM role associated with the instance, role-name is the name of the role, and role-name contains the temporary security credentials associated with the role (for more information, see Retrieving Security Credentials from Instance Metadata). Otherwise, not present. 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 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
local-ipv4 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
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 unique device number associated with that interface. The device number corresponds to the device name; for example, a device-number of 2 is for the eth2 device. This category corresponds to the DeviceIndex and device-index fields that are used by the Amazon EC2 API and the EC2 commands for the AWS CLI. 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/ipv6s The IPv6 addresses associated with the interface. Returned only for instances launched into a VPC. 2016-06-30
network/interfaces/macs/mac/local-hostname The interface's local hostname. 2011-01-01
network/interfaces/macs/mac/local-ipv4s The private IPv4 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 (IPv4). 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 IPv4 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 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
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 IPv4 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/subnet-ipv6-cidr-blocks The IPv6 CIDR block of the subnet in which the interface resides. Returned only for instances launched into a VPC. 2016-06-30
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 IPv4 CIDR block 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-blocks The IPv4 CIDR block of the VPC in which the interface resides. Returned only for instances launched into a VPC. 2016-06-30
network/interfaces/macs/mac/vpc-ipv6-cidr-blocks The IPv6 CIDR block of the VPC in which the interface resides. Returned only for instances launched into a VPC. 2016-06-30
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 IPv4 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 The ID of the reservation. 1.0
security-groups

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 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
services/partition

The partition that the resource is in. For standard AWS regions, the partition is aws. If you have resources in other partitions, the partition is aws-partitionname. For example, the partition for resources in the China (Beijing) region is aws-cn.

2015-10-20
spot/termination-time

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.

2014-11-05

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. See Instance Identity Documents. 2009-04-04
instance-identity/pkcs7 Used to verify the document's authenticity and content against the signature. See Instance Identity Documents. 2009-04-04
instance-identity/signature Data that can be used by other parties to verify its origin and authenticity. See Instance Identity Documents. 2009-04-04