commit d76f41b71ff8af0249ad87b5b304655a843e7eb4 Author: Runa A. Sandvik runa.sandvik@gmail.com Date: Sun Nov 13 17:05:38 2011 +0000

Updated build instructions for Tor Cloud --- BUILD | 140 ++++++++++++++++++++++++++++++++++++++++++----------------------- 1 files changed, 91 insertions(+), 49 deletions(-)

diff --git a/BUILD b/BUILD index 461ddc1..183ebdc 100644 --- a/BUILD +++ b/BUILD @@ -1,70 +1,112 @@ -Installation: +This document explains the process of building and publishing new Tor +images in the Amazon EC2 cloud.

- 0) Edit /etc/apt/sources.list to include multiverse - 1) Install ec2-api-tools and git-core on your laptop or build machine - 2) If the setup of openjdk-6-jre-headless is giving you a headache (e.g. crashing the instance), try using the 64-bit Ubuntu image instead. - 3) Clone https://git.torproject.org/tor-cloud.git - 4) Get the private keys (pk.cert and cert.pem) from Amazon and put them somewhere safe - 5) Run the following two commands to make sure the system knows about the private keys: +1. Set up your build environment

- # export EC2_PRIVATE_KEY=/path/to/pk.cert - # export EC2_CERT=/path/to/cert.pem + I usually spin up an Ubuntu instance in the EC2 cloud and set it up + as the Tor Cloud build machine. You can use another server, or your + laptop, if you want.

- 1) Test that ec2-api-tools is working: - root@inf0:~/Tor-Cloud# ec2-describe-regions - REGION eu-west-1 ec2.eu-west-1.amazonaws.com - REGION us-east-1 ec2.us-east-1.amazonaws.com - REGION ap-northeast-1 ec2.ap-northeast-1.amazonaws.com - REGION us-west-1 ec2.us-west-1.amazonaws.com - REGION ap-southeast-1 ec2.ap-southeast-1.amazonaws.com + You need to install two packages; ec2-api-tools and git-core. The + ec2-api-tools package can be found in multiverse, so you'll need to + add this to /etc/apt/sources.list.

- 4) Create Generate private keys for each region. For each key - generated, save it in keys/: - - # ec2-add-keypair --region us-east-1 tor-cloud-us-east-1 - # ec2-add-keypair --region us-west-1 tor-cloud-us-west-1 - # ec2-add-keypair --region us-west-1 tor-cloud-eu-west-1 - # ec2-add-keypair --region us-west-1 tor-cloud-ap-northeast-1 - # ec2-add-keypair --region us-west-1 tor-cloud-ap-southeast-1 + Note that ec2-api-tools will download and install + openjdk-6-jre-headless. There's a bug in Ubuntu which may cause your + Ubuntu instance to crash when installing that package. If that's the + case, try using a 64-bit image for the build machine instead.

+ As root, clone the Tor Cloud git repository from + https://git.torproject.org/tor-cloud.git, and create two + directories; certs and keys.

- for example: ec2-add-keypair --region us-east-1 tor-cloud-east-1 - and save the key in: ~/keys/tor-cloud-east-1.pem, don't forget to run chmod 600 ~/keys/* + Download the private certificates (pk.cert and cert.pem) for your + AWS account and put them in the certs directory. Run the following + two commands:

- Your folder should look like this: - root@inf0:~/Tor-Cloud# ls /home/architect/keys/ -lh - -rw------- 1 root root 1.7K 2011-09-12 19:11 tor-cloud-ap-northeast-1.pem - -rw------- 1 root root 1.7K 2011-09-12 19:13 tor-cloud-ap-southeast-1.pem - -rw------- 1 root root 1.7K 2011-09-12 19:14 tor-cloud-eu-west-1.pem - -rw------- 1 root root 1.7K 2011-09-12 19:09 tor-cloud-us-east-1.pem - -rw------- 1 root root 1.7K 2011-09-12 19:09 tor-cloud-us-west-1.pem + root@tor-build:~# export EC2_PRIVATE_KEY=/root/certs/pk.cert + root@tor-build:~# export EC2_CERT=/root/certs/cert.pem

+ Make sure that you also update tor-cloud/build.sh with the correct + path to pk.cert and cert.pem.

- +2. Test that everything's working

- 5) Create a Security Group called "tor-cloud-build" and allow SSH inbound traffic. + To test that everything's working, run the command + 'ec2-describe-regions'. The output should be something like this:

- 6) You are now ready to build Bridge AMIs: - For example, to build in "ap-southeast-1" region run: - ./build.sh bridge ap-southeast-1 /home/architect/keys/tor-cloud-ap-southeast-1.pem tor-cloud-ap-southeast-1 + root@tor-build:~# ec2-describe-regions + REGION eu-west-1 ec2.eu-west-1.amazonaws.com + REGION us-east-1 ec2.us-east-1.amazonaws.com + REGION ap-northeast-1 ec2.ap-northeast-1.amazonaws.com + REGION us-west-2 ec2.us-west-2.amazonaws.com + REGION us-west-1 ec2.us-west-1.amazonaws.com + REGION ap-southeast-1 ec2.ap-southeast-1.amazonaws.com

- 7) The last thing the build.sh will spit out is the region and the AMI ID: +3. Generate private keys

- ec2-describe-snapshots --region us-east-1 - IMAGE ami-5799503e + If you have done this before, but can't access the private keys, + delete the keys before generating them again (see example below):

- 8) Before other people can launch it, make sure you make it - public in AWS: + root@tor-build:~# ec2-delete-keypair tor-cloud-us-east-1 --region us-east-1

- - Images, AMIs, right clic, edit permissions, set to public + Generate private keys for each region that you are going to create + images for:

+ root@tor-build:~# ec2-add-keypair --region us-east-1 tor-cloud-us-east-1 > keys/tor-cloud-us-east-1.pem + root@tor-build:~# ec2-add-keypair --region us-west-1 tor-cloud-us-west-1 > keys/tor-cloud-us-west-1.pem + root@tor-build:~# ec2-add-keypair --region us-west-2 tor-cloud-us-west-2 > keys/tor-cloud-us-west-2.pem + root@tor-build:~# ec2-add-keypair --region eu-west-1 tor-cloud-eu-west-1 > keys/tor-cloud-eu-west-1.pem + root@tor-build:~# ec2-add-keypair --region ap-northeast-1 tor-cloud-ap-northeast-1 > keys/tor-cloud-ap-northeast-1.pem + root@tor-build:~# ec2-add-keypair --region ap-southeast-1 tor-cloud-ap-southeast-1 > keys/tor-cloud-ap-southeast-1.pem

+ Give the keys the right set of permissions with 'chmod 600 keys/*'.

- TIP: You can run the build command for all the regions at the same time. Use screen or & to send the process to background! +4. Create a security group

- - + In AWS, create a security group called "tor-cloud-build" and allow + SSH inbound. Note that you will need to create this security group in every + region that you want to create an image for.

- +5. Build Tor Cloud images

- + To build a Tor Cloud image for the region "us-east-1", cd into the + tor-cloud directory and run the following command: + + root@tor-build:~/tor-cloud# ./build.sh bridge us-east-1 /root/keys/tor-cloud-us-east-1.pem tor-cloud-us-east-1 + +6. Test the image yourself + + Just before build.sh completes the build process, it prints out the AMI ID + of the image you just created: + + Registering and publishing the image... + IMAGE ami-8939f0e0 + + You should be able to find the same image under "IMAGES" and "AMIs" in AWS. + + To test the image, click on "EC2 Dashboard" and "Launch Instance". Select + "My AMIs" in the box that pops up, and you should see the image you created + a few minutes ago. + + Go through the setup process, and wait for your instance to boot up. You'll + want to wait five minutes or so for the image to boot once, install + packages, configure Tor, and then reboot. + + Here are some things to look for once you've logged in: + + - Check that Tor is running and check the log file for errors + - Check that /etc/ec2-prep.sh says that the system has been configured as a Tor bridge + - Test the bridge yourself + +7. Make the images public + + To make the image available to the rest of the world, click on "AMIs" under + "IMAGES", right click the image you want to make public and select "Edit + Permissions". Select "Public" and click "Save". + +8. Update the Tor Cloud website + + Open tor-cloud/html/index.html and update the AMI ID for the region you + created the image for. Save the file, commit, push to git and ask someone + to update https://cloud.torproject.org/.