EC2 User Data Scripts

When you create a new EC2 instance on AWS, you have the option of passing what is know as "user data" to the instance. This is a great place to perform package updates or upgrades, and run any init scripts you may have. You can write scripts to perform different configuration tasks. One thing to note is that user data scripts and init directives only run during the first boot cycle. Restarting your instance will not re-run your user data. Passing user data in can be done on all Linux environments and cloud providers but this post focuses on AWS.

AWS EC2 Specifics

EC2 allows you to pass two types of user data: shell scripts and cloud-init directives. cloud-init directives are used to bootstrap Linux images in a cloud computing environment. For example, Amazon uses cloud-init to perform initial configuration of the ec2-user account on Amazon Linux AMIs. You can read more about them here: cloud-init directives.

On AWS user data can be passed through the launch wizard as plain text, as a file (this is useful for launching instances using the command line tools), or as base64-encoded text (for API calls).

Example User Data Script

#!/bin/bash             
yum update -y  
yum install httpd -y  
service httpd start  
chkconfig httpd on  
aws s3 cp s3://mywebsitebucket/index.html /var/www/html  

First we begin by updating system packages with yum. We then use yum again to install Apache. After Apache is installed we start the Apache service. We then use chkconfig to configure Apache to automatically start whenever the system is restarted. The final command copies the file index.html from an S3 bucket and places it in the /var/www/html directory (the default document root for Apache). Notice the yum commands used the -y flags since you can't use interactive commands when passing in user data.

Note: The final command uses the AWS Command Line Interface (CLI) to work with S3. AWS Linux AMI's come with the CLI already pre-installed.

Important Points

  • User data scripts and cloud-init directives only run during the first boot cycle
  • Scripts entered as user data are executed as the root user
  • Scripts do not run interactively
    • You cannot include commands that require user feedback (such as yum update without the -y flag).

Troubleshooting

If you need to troubleshoot or verify that your user data input worked correctly, you can check the cloud-init output log file which can be found here:

/var/log/cloud-init-output.log

Chris Longe

Veteran DJ/Producer (in hiatus) • Computer Engineering graduate from UT Austin • Software Engineer at @CapitalOne • The revolution will be #swiftlang!

Washington D.C.