Many Ubuntu and Debian images for Amazon EC2 include a hook where scripts passed as user-data will be run as root on the first boot.
At Campus Explorer, we’ve been experimenting with an approach where the actual user-data is a very short script which downloads and runs other scripts. This idea is not new, but I have simplified the process by creating a small tool named runurl which adds a lot of flexibility and convenience when configuring new servers.
Usage
The basic synopsis looks like:
runurl URL [ARGS]...
The first argument to the runurl command is the URL of a script or program which should be run. All following options and arguments are passed verbatim to the program as its options and arguments. The exit code of runurl is the exit code of the program.
The runurl command is a very short and simple script, but it makes the user-data startup scripts even shorter and simpler themselves.
Example 1
If the following content is stored at http://run.alestic.com/demo/echo
#!/bin/bash
echo "$@"
then this command:
runurl run.alestic.com/demo/echo "hello, world"
will itself output:
hello, world
You can specify the “http://” in the URLs, but since it’s using wget to download them, the specifier is not necessary and the code might be easier to read without it.
Example 2
Here’s a more substantial sample user-data script which invokes a number of other remote scripts to upgrade the Ubuntu packages, install the munin monitoring software, install and run the Folding@Home application using origami with credit going to Team Ubuntu. It finally sends an email back home that it’s active.
This sample assumes that runurl is installed on the AMI (e.g., Ubuntu AMIs published on http://alestic.com>). For other AMIs, see below for additional commands to add to the start of the script.
#!/bin/bash -ex
runurl run.alestic.com/apt/upgrade
runurl run.alestic.com/install/munin
cd /root
runurl run.alestic.com/install/folding@home -u ec2 -t 45104 -b small
runurl run.alestic.com/email/start youremail@example.com
Note that the last command passes a parameter to the script, identifying where the email should be sent. Please change this if you test the script.
With the above content stored in a file named folding.user-data, you could start 5 new c1.medium instances running the Folding@Home software using the command:
ec2-run-instances \
--user-data-file folding.user-data \
--key [KEYPAIR] \
--instance-type c1.medium \
--instance-count 5 \
ami-ed46a784
You can log on to an instance and monitor the installation with
tail -f /var/log/syslog
Once the Folding@Home application is running, you can monitor its progress with:
/root/origami/origami status
and after 15 minutes, check out the Munin system stats at
http://ec2-HOSTNAME/munin/
Expiring URLs
One of the problems with normal user-data scripts is that the contents exist as long as the instance is running and any user on the instance can read the contents of the user-data. This puts any private or confidential information in the user-data at risk.
If you put your actual startup code in private S3 buckets, you can pass runurl a URL to the contents, where the URL expires shortly after it is run. Or, the script could even delete the contents itself if you set it up correctly. This reduces the exposure to the time it takes for the instance to start up and does not let anybody else access the URL during that time.
Updating
Another benefit of keeping the actual startup code separate from the user-data content itself is that you can modify the startup code stored at the URL without modifying the user-data content.
This can be useful with services like EC2 Auto Scaling, where the specified user-data cannot be dynamically changed in a launch configuration without creating a whole new launch configuration.
If you modify the runurl scripts, the next server to be launched will automatically pick up the new instructions.
Bootstrapping
The runurl tool is pre-installed in the latest Ubuntu AMIs published on http://alestic.com. If you are using an Ubuntu image which does not include this software, you can install it from the Alestic PPA using the following commands at the top of your user-data script:
codename=$(lsb_release -cs)
echo "deb http://ppa.launchpad.net/alestic/ppa/ubuntu $codename main"|
sudo tee /etc/apt/sources.list.d/alestic-ppa.list
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys BE09C571
sudo apt-get update
sudo apt-get install -y runurl
If you are using a Linux distro other than Ubuntu, you can install runurl using the following commands at the top of your user-data script:
sudo wget -qO/usr/bin/runurl run.alestic.com/runurl
sudo chmod 755 /usr/bin/runurl
The subsequent commands in the user-data script can then use the runurl command as demonstrated in the above example.
SSL
To improve your certainty that you are talking to the right server and getting the right data, you could use SSL (https) in your URLs. If you are talking to S3 buckets, however, you’ll need to use the old style S3 bucket access style like:
runurl https://s3.amazonaws.com/run.alestic.com/demo/echo "hello, mars"
This is probably not as critical when accessing it from an EC2 instance as you’re operating over Amazon’s trusted network.
Caveats
There are a number of things which can go wrong when using a tool like runurl. Here are some to think about:
Only run content which you control or completely trust.
Just because you like the content of a URL when you look at it in your browser does not mean that it will still look like that when your instance goes to run it. It could change at any point to something that is broken or even malicious unless it is under your control.
If you depend on this approach for serious applications, you need to make sure that the content you are downloading is coming from a reliable server. S3 is reasonable (with retries) but you also need to consider the DNS server if you are depending on a non-AWS hostname to access the S3 bucket.
The name run.alestic.com points to an S3 bucket, but the DNS for this name is not redundant or worthy of use by applications with serious uptime requirements. This particular service should be considered my playground for ideas and there is no commitment on my part to make sure that it is up or that the content remains stable.
If you like what you see, please feel free to copy any of the open source content on run.alestic.com and store it on your own reliable and trusted servers. It is all published under the Apache2 license.
Project
I’m using this simple script as an opportunity to come up to speed with hosting projects on Launchpad. You can access the source code and submit bugs at
You can also use launchpad and bazaar to branch the source into parallel projects and/or submit requests to merge patches into the main development branch.
[Update 2009-10-11: Document use of Alestic PPA]
Leave a comment