Automate Your EC2 Instance Setup with EC2 User Data Scripts

If you find yourself executing the same set of commands on your new EC2 instances each and every time you launch them and you are not making use of EC2 User Data, then this article is for you! Read on to learn how to use the EC2 User Data feature to automatically run commands when your instances first launch to automate your common setup process.

What is EC2 User Data

Simply put User Data is a set of commands which will be executed on an EC2 instance when it is first launched. User data can be used on both Linux and Windows systems. Below are some of the key attributes for user data stated on the AWS website.

• 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. The Amazon EC2 console can perform the base64 encoding for you or accept base64-encoded input.
• User data must be decoded when you retrieve it. The data is decoded when you retrieve it using instance metadata and the console.
• If you stop an instance, modify its user data, and start the instance, the updated user data is not executed automatically when you start the instance. However, you can configure settings so that updated user data scripts are executed one time when you start the instance or every time you reboot or start the instance (more about this below).

Why should you use EC2 User Data

A lot of times when you are launching a new instance there can be a set of common tasks you perform as part of an initial instance setup procedure. For example if you are launching a lot of instances that are being used as web servers you may want to install IIS on a Windows Server or Apache on a Linux machine.

The User Data field allows you to specify these commands in a command line format which will then execute when the instance is initially launched.

How to use EC2 User Data

When you launch a new EC2 instance using the Launch Wizard, when you get to the Configure Instance Details page you’ll see a heading called “Advanced Details”. If you expand this you’ll see the User Data field.

You can add user data directly into the text box or from a file on your local computer. When entering user data into the text box or via the file upload option the data is limited to a size of 16K KB. If you need to enter user data commands greater than 16 KB in size you will need to base64 encode the commands manually first before entering them into the User data text box. Then check the “Input is already base64 encoded” checkbox.

EC2 user data is different for Windows and Linux machines, depending if you are launching a Windows or Linux instance will determine the format of the user data commands you will use.

Adding EC2 User Data for Linux Instances

Specifying EC2 user data for a Linux instance is simple. Start off by specifying a hashbang to the bash shell followed by whatever commands you want to be executed.

The example below shows a simple Apache installation which will take place when the instance first launches.

#!/bin/bash
yum update -y
yum install httpd mod_ssl
service httpd start
chkconfig httpd on

Adding EC2 User Data for Windows Instances

User Data commands for Windows can either be executed via the command prompt of via PowerShell.

Running Command Prompt Commands in EC2 User Data

To execute your startup commands in a Command Prompt window (batch commands) you need to enclose your commands with the <script></script> tags. The following example updates the server timezone at launch.

<script>
REM Set timezone
tzutil /s "Singapore Standard Time"
</script>

Running PowerShell Commands in EC2 User Data

If you want to run your startup commands in PowerShell you need to enclose them in <powershell></powershell> tags. The following example shows the automatic installation of IIS from PowerShell.

<powershell>
# Install IIS
Install-WindowsFeature -Name Web-Server -IncludeManagementTools
</powershell>

Executing EC2 User Data Every Time Instance Starts

By default user data commands are run once when the instance is first launched. If you would like your commands to run every time the instance is started you need to include the <persist>true</persist> in your user data.

<script>
REM Command prompt commands which will execute every time the instance starts.
</script>
<persist>true</persist>

<powershell>
# PowerShell commands which will execute every time the instance starts.
</powershell>
<persist>true</persist>

The examples given here are very simple and were created to show how easy it is to make use of the EC2 User Data feature. From here you can create your own scripts for your use cases.

If you enjoyed this article please share it and feel free to leave your comments below – Mathew