Homework Assignment #0 — Dev Setup

There are no late days for this assignment: we want you to be on track for starting HW1, which is due soon after! You must complete this assignment individually, but may use or consult any resources you like.

EECS 481 is different from other EECS courses offered here. There is a larger focus on software process, reading code, and using large systems to accomplish tasks. You will be expected to develop and maintain programs and scripts in multiple languages using multiple tools. As a result, I want to help you prepare a suitable development environment for the assignments in this course. In previous semesters, students have reported creating a Virtual Machine to be useful for the assignments in this class. HW0 will guide you in doing just that.

This assignment will help you create a development environment that matches the autograder environment. If you are not familiar with Linux command line tools, this assignment is a great place to start.

The assignments in this course have been designed around an x86_64 Ubuntu 16.04 LTS environment. All of the assignments are known to work in this environment. Officially, you have to use this environment. (If you do not then you will likely run into issues that are not covered in the homework specifications. That is, later commands will not work for you and you will be unable to complete the homeworks.) Different versions of tools and libraries are installed by default in different versions of Linux. As a result, if you deviate from the suggested x86_64 Ubuntu 16.04 environment, you may encounter corner cases that cause test cases to fail on the autograder. In some cases, the staff may direct you to set up an Ubuntu 16.04 Virtual Machine if you have not done so and are stuck on some assignments. Ultimately, it is your responsibility to read documentation and install supported tools. This HW0 spec is meant to help you walk through the creation of an x86_64 Ubuntu 16.04 environment.

Two Options — Local or Cloud

You must select one of the following two full-credit options for this assignment:

1. Option 1 ("Local"): Set up a local Ubuntu 16.04 Virtual machine on your computer. This is the most popular option for most students. It has a nice UI that makes it easy to navigate.
   • Some students may have WSL Ubuntu set up (e.g., for 281). Unfortunately, it is a different version of Ubuntu and will not work for this class: follow the instructions below. However, your experience setting it up will help you here!
   • Some student reports that VirtualBox is not compatible with the new Macbooks (e.g., with M1 and M2 chipsets). If you are using such a Macbook, you may have to select the Option 2 below and use the Cloud instead of your local machine.
   • Some students may be tempted to install an ARM Ubuntu setup, but unfortunately the x86_64 architecture is required. (If you're not certain what this means, you can ignore it.)
   • Some students already have newer versions of Ubuntu installed. Crushingly, you will need the legacy version mentioned here: follow the instructions below.
   • Some students have experience with docker. Unfortunately, docker will not suffice here (but experience with it will help you): follow the instructions below.
2. Option 2 ("Cloud"): Set up an Amazon EC2 cloud instance with Ubuntu 16.04 running on it. This option will work if you have a slower or older computer. Start early; Amazon takes up to 24 hours to verify cloud computing accounts. This option involves more of a command-line interface but typically runs some course tools a bit faster than a local machine. In addition, while Amazon does offer "free tier" service, and we explain how to ensure you are using it, it is possible to mistakenly leave the free tier and owe them money.

Both options should work with all assignments in this course. Option 1 (local VM) will have you install VirtualBox on your computer, download an Ubuntu 16.04 installation image, and install x86_64 Ubuntu 16.04 in your virtual machine. A reasonably modern computer (e.g., at most 5 years old) should be able to run a VM guest without issue. However, some students report that the VM executes too slowly (e.g., the mouse is laggy, keystrokes are missed, programs take too long, etc.). If your VM guest is too slow, you can consider using Option 2 instead (see below).

First, read the summary of virtual machines and cloud computing below. Even if you are familiar with the concepts from previous experiences, this course may use slightly different terminology, and I recommend that you skim the material.

Background — Virtual Machines and Cloud Computing

A Virtual Machine is an emulation of a computer system. Loosely, you can think of a VM as a program that can run an entire virtual computer system. Virtual machines are powerful software systems that enable running software designed for one operating system inside another operating system.

For example, you can use your Windows host computer to run a Virtual Machine that contains a Linux operating system. Consider the image below:

This is a Windows 10 host computer running three different Virtual Machine guests. The guest instances are complete (virtual) environments that are isolated from the host. All of the guests share the host's hardware as they execute — each window in the screenshot above lets you interact with a separate emulated guest.

Thus, even though the host is a Windows computer, you can use one of the guests to execute Linux software inside the guest. Virtual Machines can be used in many combinations. You can have a Windows, Linux, or Mac host computer, and run arbitary numbers and combinations of Linux and Windows guests. Finally, guests are stored as files in the host computer — this means you can move your VM guest from one host to another by transferring that file around.

---

Option 1 ("Local"): You can choose to set up and run your own Ubuntu 16.04 virtual machine locally. This will allow you complete all of the assignments in this course within that virtual machine. However, some students report that the VM guest runs too slowly (especially if you do not have enough RAM in your computer). If you find that a local VM is too slow, you can use Option 2 instead.

---

Virtual machines are a critical part of Cloud computing. You can "rent out" computing resources from a provider like Amazon EC2 or Microsoft Azure to do whatever computation you might need. Amazon EC2 and Microsoft Azure both offer you virtual machine guests that run on their hardware. Thus, you can get access to a virtual machine running whatever operating system you like to run a variety of software.

---

Option 2 ("Cloud"): If you find that a local VM is too slow, you can instead get a free Ubuntu 16.04 virtual machine from Amazon EC2. Amazon EC2 "Elastic Cloud Compute" is a service that lets you buy and configure virtual machines. Option 2 has you setup and launch an Ubuntu 16.04 cloud instance (this is free if you are a student).

Linux Fundamentals

Many of the assignments are easier to complete on Linux or similar command-line systems. EECS 481 professor Kevin Leach has prepared a (long) video that provides a gentle introduction to a number of Linux concepts. This video is optional, but you may find it useful if you are less familiar with the Linux environment.

There are timestamps in a comment below the video that contains points of interest, such as:

• terminals
• environment variables
• scripts in the shell
• compiling programs from source
• using ssh

The first half is more about terminals and shells (why do we have to type ./a.out? why can't we just say a.out?), and the second half is more about compiling programs from source. The video also covers elinks in particular, which is a terminal-based browser program.

Option 1 — Local Virtual Machine

You can set up your own local virtual machine for free. However, before you proceed, consider checking whether your CPU supports accelerated virtualization. If your CPU does not support virtualization extensions, then your VM may run slowly. If that's the case, consider Option 2 for this assignment instead.

You will need:

• A copy of VirtualBox for your operating system. General download link (look under "Platform Package" or similar).
• A copy of 64-bit Ubuntu 16.04 (Download — 64-bit is required here: don't use 32-bit)
• When something goes wrong during this installation, we recommend that you search this webpage and aslo look for previous posts on the forum. Some solutions may be listed a little lower on the webpage than when you encounter them. Similarly, while we know students are very wary of searching on Piazza, in this particular instance is actually works quite well to filter on the hw0. You can click on a topic tag in Piazza to only show posts related to that topic, like so:

  

  Macs typically give students many more issues than Windows machines, so if you are a student using a Mac, looking to see if the issue is already addressed can be a big time saver.

VirtualBox

VirtualBox is a Virtual Machine Manager. You install VirtualBox on your host computer (i.e., as a regular program or app). Then, you use VirtualBox to create a virtual machine guest. Once you have created a guest, you install Ubuntu 16.04 inside of the guest. Then, you can start the guest and have a complete Ubuntu 16.04 environment within that guest.

Installing VirtualBox

You can install VirtualBox with the default settings. For your reference, screenshots of the course staff completing the installation are shown below:

If you receive a "The installation failed." message on a Mac, you can resolve the issue by going to Security and Privacy and allowing the installation.

Creating a Virtual Machine

After installing VirtualBox, it will display the main VM Management console, which we can use to create a New Machine (see circular highlight in upper left):

Next, configure your virtual machine. Select Type as Linux and Version as Ubuntu 64-bit. (If you only see options for 32-bit and do not see options for 64-bit, you will not be able to complete this option and will instead have to use the Amazon EC2 Cloud instance option. This happens to some students with older 32-bit Mac machines that cannot emulate 64-bit guests.) You can name your VM whatever you like. We recommend using at least 2048MB of Memory. See highlights below:

Next, it will ask you to create a storage device. Remember, you are creating a virtual machine — an entire simulated computer. That includes simulating a hard disk for storage. This is represented as a large (> 20GB file) on your host computer. We recommend at least 20GB, and you can choose "dynamically allocated" (or not check "pre-allocate full size") to save space:

After this step, you will have successfully created a Virtual Machine. Now, you have a bare system with nothing installed on it. Next, we must install an OS on it to run the VM.

Installing an OS in the Guest VM

After creating a VM, we need to install Ubuntu 16.04 on it to help run software. Remember downloading ubuntu-16.04.7-desktop-amd64.iso as indicated above? This is a Disk Image — we need to attach the OS Disk Image into the VM.

On the VM Management window, right click the VM you just created, and click Settings:

Next, click on Storage, then click on the Empty IDE Controller (your version of VirtualBox may call this a CD drive, Optical storage drive, or similar. Regardless, you should be able to select a virtual disk image). Click the Disk icon, then click Choose disk file...:

Then, select the ubuntu-16.04.7-desktop-amd64.iso file you downloaded earlier. This places the Ubuntu 16.04 installation medium in the VM's disk drive. Click OK, and you are now ready to start your VM from the Manager:

If you receive a "Kernel driver not installed" error, follow the instructions online for how to resolve the issue.

The Virtual Machine will now boot and load the Ubuntu 16.04 installation. The VM opens in a new window — you can think of this window as the virtual "screen" that lets you see what's happening in the emulated system. You can follow through the normal Ubuntu 16.04 installation:

Note: If the VM asks you to select a startup disk, you need only select the ubuntu-16.04.7-desktop-amd64.iso file. You want the VM to boot from the installation media so you can install Ubuntu within the guest.

We recommend opting to install updates and third-party software. It should not affect the system one way or another:

You can select Erase disk and install Ubuntu. This is only referring to erasing the "virtual" disk you created earlier with the VM.

If the Ubuntu installer crashes halfway through the installation, some students report that the issue can be resolved by updating VirtualBox to the latest version (at least 6.1.26).

If you are receiving an error like the following disc images couldn't be opened for the reason of no mountable file systems, you may be able to resolve the issue by following recommendations online.

Note: Sometimes during installation, students find that a window is too large to display all the buttons. You can actually move the window like normal to reveal the Continue button (just click to drag the window like any other — the window inside the Virtual Machine, not the Virtual Machine itself):

Next, it will ask you to create an account for logging in. You can put whatever credentials you like here — it will not have any bearing on your host computer. This is merely for an account on the guest VM. Just make sure you don't forget whatever password you choose.

Next, you just wait a bit for the OS to install inside the guest. It might take a few minutes to complete. Eventually, you'll see a screen asking you to remove installaton media and restart. You can just click restart (on the guest) and you'll be all set!

Install VirtualBox Additions

One thing you'll notice when you install your VM successfully is that the window is small. In our opinion, one thing that makes the experience way better is the VirtualBox Additions package. It provides a number of "Quality of Life" features when using VMs. It's essentially a helper program you install inside the VM guest that makes it "aware" that it's running inside of a VM. To install, click Devices, then Insert Guest Additions CD Image...

Eventually, a window pops up asking if you want to run the media. Just click Run.

After installing, you can reboot the VM image. One more step to make sure gcc (a compiler for C and C++ programs) is installed in your guest. In a terminal, use:

sudo apt-get update
sudo apt-get install gcc

You're all set! You can proceed to Submitting the assignment!

Option 2 — Amazon EC2

Note well: This option will take longer than Option 1. Amazon AWS accounts can take up to 24 hours to verify, which means you may have to wait before you can continue to Step 3. Start early!

You will need a Secure Shell (SSH) client. You should already be familiar with SSH from using CAEN servers remotely. SSH allows you to remotely interact with a server. When you SSH to a remote computer, you have access to a command prompt that runs software on that computer. We will be using SSH to interact with a virtual machine we create in the cloud with Amazon EC2. On Windows, I recommend using WSL to run SSH. You can also use PuTTY. On Mac, you should already have ssh installed. Open a terminal and you can run ssh. On Linux, you can use ssh, but you may need to install it first (e.g., sudo apt-get install openssh or similar, depending on your platform). It is your responsibility to understand how to use SSH, though we give some pointers below.

Amazon EC2 is a cloud computing service that allows you to rent virtual machines that you can ssh to and run programs like any other computer. Amazon offers a large number of cloud-based services all under the umbrella of AWS (Amazon Web Services). EC2 is a subset of AWS. In this section, you will create an AWS account to manage EC2 virtual machines.

You can sign up for a new account on Amazon EC2, and in doing so, you get 12 months of free access to a virtual machine that is enough to complete the assignments in this course. If you do not already have an Amazon EC2 account, navigate to https://aws.amazon.com/ec2/ and click "Create new account" in the upper right.

In most cases, Amazon EC2 only offers free access within the first 12 months of an account. If you already have an older account (e.g., for another class) you may need to create a new, second account to get more free access.

Complete the sign up process. You may be prompted for credit card information, however you do will not be charged as long as you create only one virtual machine on the free tier. You then will have access to the Amazon AWS Console. If you are prompted, you want to sign in as a "Root" user for the AWS console.

Creating a New VM

Now that you have created an account, you can use the AWS Console to help manage and launch virtual machine instances. We will walk you through the steps to create an Ubuntu 16.04 VM below.

(1) Open the AWS Console

After you create an AWS account, you can visit the AWS Console at https://console.aws.amazon.com. At the console, you should be greeted with a large screen full of many services. See highlight on left: Click to see AWS Console screenshot.

(2) Open the EC2 Manager

From the AWS Console, click the EC2 link to open the Elastic Cloud Compute manager. The EC2 Manager lets you manage and launch Instances, which are virtual machines that you configure. The first thing we need to do is configure and launch a new instance. Click the Launch Instance button.

(3) Choose an Ubuntu 16.04 Instance

This is the most important step. You must select an Ubuntu Server 16.04 LTS (HVM), SSD Volume Type instance. This is a free tier eligible instance that contains an environment suitable for completing the rest of the assignments. Don't pick other versions of Ubuntu (NOT 18.04 or 20.04, etc.). The autograder uses Ubuntu 16.04, so if you want the smoothest experience, use that version.

As of 2024, the ami-07b1c5d8038f83864 Ohio (us-east-2) instance AMI is known to work (and was created by Rui Dong, a former 481 staff member, specifically for this purpose).

(4) Configure Your Instance

After you select the image to launch, it may ask you a few questions about storage (pick the default if so).

We recommend selecting 30 Gigabytes for the volume or disk size. This is the maximum size availabel for the free tier. The default may be 10 GiB, but students sometimes hit that limit during 481. (You can complete all of the assignments with a 10 Gigabyte volume, but you may have to move HW1, HW2 and HW3 files off to separate storage and delete them to make room for HW4 and HW5, etc.)

Usually, it will skip ahead and ask you about instance details. You want to pick the free version, called a t2.micro instance. If you were using cloud computing for a business or another project, you could configure resources like (a) how many CPUs, (b) how much RAM, and (c) what type of storage you get on the VM. For this course, just pick t2.micro to get the free level.

(5) Configure Authentication

After you set up your instance, you need to create a way to login. This is a tricky security problem because Amazon wants to give you root (Administrator) access to your new instance. The way they do this is by using asymmetric key encryption. Basically, Amazon will let you download a file that serves as your credentials. Rather than entering a password, you will provide this special file to let you login. Courses such as EECS 388 or EECS 485 provide more information about asymmetric key encryption.

Now, you will be prompted to set up credentials for logging in. Select Create a new key pair and type in a name such as eecs481 (see the screenshot below). (If you are given a key type option, like "RSA" vs. "ED22519", pick "RSA".) Then, click Download Key Pair. It is imperative that you keep this file in a secure location. Do not upload it to GitHub, do not move it around. This is basically like a password for accessing your instance — you wouldn't want someone malicious to access your instance and do something bad with it.

Once you had downloaded your Key Pair, you should be able to Launch your instance. Do so and continue. There is a screenshot below showing what you should see after launching your instance.

Also, from the main EC2 Manager, you can confirm that your instance is running:

(6) Connect to Your Instance

At this point, you have set up an Ubuntu 16.04 instance on EC2 and created associated credentials. You now have a virtual machine running in the cloud that you can connect to. Much like accessing CAEN, you will use ssh to connect to your instance. This is the recommended way — you could technically install a front-end and use remote desktop software, however we strongly recommend using the command line, since you will be using the CLI in many of the course assignments.

From the EC2 Management Dashboard, right-click your running instance. You should see a menu pop up like below:

Click Connect. It will pop up a window giving you a number of options. Pick the SSH Client tab to see how to connect via ssh:

On this window, you will see the hostname of your EC2 instance to which you can ssh, as well as a number of instructions for connecting.

Some students, especially those using Mac computers, report receiving permission errors when they try to SSH into their EC2 instances:

In this case, a command like

chmod go-rwx /path/to/eecs481.pem

mkdir -p ~/.ssh/
cp /path/to/your/downloaded/eecs481.pem ~/.ssh
chmod 400 ~/.ssh/eecs481.pem 

Recall you downloaded a eecs481.pem file when you set up authentication for your instance (see part 5 above). You must specify this file on your SSH client to connect to your instance.

First, you must provide the correct access permissions to the eecs481.pem file. Usually, this means running chmod 400 /path/to/your/eecs481.pem. Once you do so, you can use the ssh command directly:

ssh -i /path/to/your/eecs481.pem ubuntu@<your-EC2-hostname-here>

(You must substitute in the path to your downloaded eecs481.pem file as well as the hostname of your EC2 instance, which takes the form of ec2-X-Y-Z.us.W.compute.amazonaws.com for some values of W, X, Y, and Z.)

If you receive an error that the path is too long for Unix domain socket or the like, open ~/.ssh/config in a text editor and modify the control path to match this (reference):

Host *
        ControlPath ~/.ssh/control/%C
        ControlMaster auto

At this point, you should be logged in to your EC2 Instance! See below for an example of connecting to such an instance from the WSL environment:

Once you're all finished, you need one more step to install gcc (a compiler for C and C++ programs):

sudo apt-get update
sudo apt-get install gcc

Then, you can proceed to Submitting the assignment below!

You can safely stop the VM instance when you aren't using it (e.g., between homeworks) and restart it when you are.

Option 2 — Alternate: Google Cloud Platform

It is also possible to complete the assignments using the Google Cloud Platform (GCP) instead of Amazon EC2. However, this option is unsupported by the course staff — by all accounts it works fine, but we won't be in a position to help you with it. Using GCP may be a better fit for students who cannot make an Amazon account or already have Google Cloud experience.

Follow this GCP Quick Start guide for EECS 481. Be sure to double-check the Commands you need to run for environment setup section for commands you will need for HW0, HW2, etc.

Submitting HW0

Note well: after submitting this assignment, you are welcome to use whatever environment you like for this course instead, but you may run into issues this semester with compiling or running some software. Debugging systems integration issues is good practice (and indeed, an intentional part of this courses assignments). Unfortunately, we cannot support every combination of student hardware and software. Thus, the officially supported environment in Ubuntu 16.04.

Complete the assignment through autograder.io (as per the main course webpage). For HW0, you are asked to submit a single file named output.txt. Obtain your output.txt file by running the following commands in your virtual machine guest:

cd ~
wget https://web.eecs.umich.edu/~weimerw/481/hw0/hw0sample
chmod u+x hw0sample
./hw0sample

If you receive an error such as "failed: Temporary failure in name resolution. wget: unable to resolve host address 'web.eecs.umich.edu'" on your VM, make sure your guest is connected to the Internet by switching it to bridged mode.

After invoking ./hw0sample, you will find a file output.txt in your home directory. Upload that file to the autograder and you're done!

scp -i /path/to/your/eecs481.pem ubuntu@>your_EC2_hostname<:/path/to/some/remote/file.txt  /path/to/where/you/want/to/download/it/target.txt

scp -i /path/to/your/eecs481.pem /path/to/local/file/to/upload.txt ubuntu@>your_EC2_hostname<:/path/to/some/remote/target.txt

Final Remarks

There is a fair bit of systems programming in this course. We will use a mixture of command line tools, multiple languages, and other large projects that you may not have seen, written, or used before. That's the point. In software engineering, much of your day-to-day work will involve reading code and documentation, as well as getting things set up to run. We are big believers that this type of experience is some of the most valuable you can acquire as an undergraduate student — it makes you more productive at other tasks.

This assignment is not meant to take more than 2 hours (excluding the time taken to download Ubuntu 16.04 in Option 1, or the Amazon AWS signup time in Option 2). Please use this assignment as a gauge for your technical preparedness in this course. A big component of the assignments is "read the docs, figure out how to invoke the tools." We acknowledge this is not for everyone — indeed, one purpose of having this (and HW1) due so early is to help you decide whether you like this style of assignment. Please contact us on Piazza if you have any questions!