Work with instance user data

You can use instance user data to customize your instances. When you launch an instance, you can store parameters or scripts as user data. Any scripts in user data are run when you launch the instance. You can view user data as an instance attribute. You can also view user data from your instance through the Instance Metadata Service (IMDS).

Considerations

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

• User data must be base64-encoded. The Amazon EC2 console can perform the base64-encoding for you or accept base64-encoded input.

• User data is limited to 16 KB, in raw form, before it is base64-encoded. The size of a string of length n after base64-encoding is ceil(n/3)*4.

• User data must be base64-decoded when you retrieve it. If you retrieve the data using instance metadata or the console, it's decoded for you automatically.

• If you stop an instance, modify its user data, and start the instance, the updated user data is not run when you start the instance.

• User data is an instance attribute. If you create an AMI from an instance, the instance user data is not included in the AMI.

Specify instance user data at launch

You can specify user data when you launch an instance. For console directions, see Specify instance user data at launch. For an example that uses the AWS CLI, see User data and the AWS CLI.

Modify instance user data

You can modify user data for instances with an EBS root volume. The instance must be in the stopped state. For console directions, see View and update the instance user data. For an example that uses the AWS CLI, see modify-instance-attribute.

Retrieve instance user data from your instance

Note

The examples in this section use the IPv4 address of the IMDS: 169.254.169.254. If you are retrieving instance metadata for EC2 instances over the IPv6 address, ensure that you enable and use the IPv6 address instead: fd00:ec2::254. The IPv6 address of the IMDS is compatible with IMDSv2 commands. The IPv6 address is only accessible on Instances built on the Nitro System.

To retrieve user data from an instance, use the following URI.

http://169.254.169.254/latest/user-data

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

This example returns user data that was provided as comma-separated text.

IMDSv2

[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/user-data
1234,john,reboot,true | 4512,richard, | 173,,,

IMDSv1

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

This example returns user data that was provided as a script.

IMDSv2

[ec2-user ~]$ TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"` \
&& curl -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/user-data
#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on

IMDSv1

[ec2-user ~]$ curl http://169.254.169.254/latest/user-data
#!/bin/bash
yum update -y
service httpd start
chkconfig httpd on

Retrieve instance user data from your computer

You can retrieve user data for an instance from your own computer. For console directions, see View and update the instance user data. For an example that uses the AWS CLI, see User data and the AWS CLI.