All programming assignments must compile and run on a standard 32-bit Ubuntu 16.04 system ("standard" means following all the instructions on this web page). To minimize the chance of hardware incompatibility, the best way to run Ubuntu Linux is to first install a virtual machine hypervisor (Oracle VirtualBox is recommended because it's free and available on both Windows and Mac OS X machines), then install 32-bit Ubuntu 16.04 into a virtual machine inside the hypervisor. This web page contains instructions on how to first install a virtual machine hypervisor (Oracle VirtualBox in particular) into your desktop/laptop, and then install a standard 32-bit Ubuntu 16.04 system into a virtual machine running inside the virtual machine hypervisor.

Another major advantage of using this approach is that you can install as many virtual machines into VirtualBox. Therefore, you should install a standard 32-bit Ubuntu 16.04 into a virtual machine for the sole purpose of doing programming assignments for this class. Do NOT use this virtual machine for anything else and follow the instructions here as closely as possible!

You need a machine that runs a real desktop operating system, such as Windows 10 or Mac OS X. If you can only get your hands on a machine that runs Android/iOS/ChromeOS or Windows 8 or something even older, please talk to the instructor before proceeding. (If you are considering buying a machine for school, it's best that you buy a Intel/AMD-based machine that runs Windows 10 or Mac OS X.)

If you have a Windows machine or an Intel-based Mac OS X machine, the minimum hardware requirement for running a virtual machine hypervisor is that you should have an Intel Core i3 or faster processor with 4GB or more memory. If your laptop/desktop has a slower CPU, non-Intel compatible CPU, or less than 4GB memory, please talk to the instructor before proceeding.

We can ONLY grade your programming assignments on a standard 32-bit Ubuntu 16.04 machine running QEMU 2.5. (Furthermore, the kernel assignments are ONLY known to work properly on 32-bit Ubuntu 16.04.)  Therefore, you MUST implement and test your programming assignments on this platform. If you don't want to install Ubuntu 16.04 on your machine because you already have another version of Ubuntu installed, please talk to the instructor before proceeding. If you choose to implement and test your programming assignments on something other than a standard 32-bit Ubuntu 16.04, you may end up getting zeroes in your programming assignments since the graders are not allowed to grade your assignments on other platforms or on your machine!

Ubuntu 16.04 is not the current release of Ubuntu. If you just go to the Ubuntu web site, you will be downloading the WRONG version of Ubuntu. Also, it's best not to install Ubuntu 16.04 from scratch. It's better to install from a virtual appliance.

If you are running Windows 10 and your machine supports "virtualization" in BIOS, although it's not required, it's a good idea to have it enabled so things can run faster. If you don't know how to do that or check if you machine supports virtualization, just google "Enable virtualization in BIOS in Windows 10".

Please do NOT use Ubuntu 17.04 or above to do our programming assignments. The graders are not permitted to grade your programming assignments on those systems. I also know for sure that our kernel assignments are NOT compatible with Ubuntu 17.04 or above. You should definitely NOT use Ubuntu 17.04 or above to do our kernel assignments.

The New Mac

Apple threw us a curve at the end of last year by switching to a non-Intel/AMD CPU for their new Macs. These systems are so new, it's not clear if VirtualBox would work on such a system. Even if VirtualBox works on such a system, it's not clear if you can run a 32-bit Ubuntu 16.04 system inside of it. If you have such a system, it would be great if you can follow the installation procedure mentioned below and let me know if it works on such a system or not.

If it ends up that there is no way to run a 32-bit Ubuntu 16.04 system on it and the only machine you can use to work on our assignments is such an machine, then we have to have an alternative for you. Here are the two options.

  • Borrow an Intel/AMD-based laptop from your family or friend, if they have a spare one!

  • USC has an equipment rental program where you can rent a laptop (most likely, running Windows 10) for free for an entire semester (subject to availability). My understanding is that this is free of charge. But of course, they may change their policy.

  • Another option is to run a standard 32-bit Ubuntu 16.04 system on Viterbi's MyDesktop (VMware Horizon) environment To work on this system, you need to have a decent Internet connection since you can only access this system when you have a live Internet connection (in that respect, it's kind of like using Zoom). By default, students do not have accounts on MyDesktop. Request to create accounts on MyDesktop must go through me. Therefore, if your system does not meet the above requirements and it's the only systemm you have access to, please let me know (and tell me what system you do have) so I can make a request on your behalf.

The only virtual machine hypervisor platform that I would recommend is the Oracle VirtualBox. Oracle VirtualBox is free and runs well on both Windows 10 and Mac OS X. (I was told that it also runs on a Linux machine, although I have never tried it myself.)

There may be other ways to install a 32-bit Ubuntu 16.04 system so you can do your programming assignments. In the interest of time, we will only present one solution for everyone. If you are thinking about doing it in a different way, please talk to the instructor before proceeding to see if it's going to acceptable. The goal is for students to do the programming assignments. I really don't want students to waste time on system issues because that's not what this class is about.

Below are my instructions on how to install VirtualBox and then how to install Ubuntu 16.04 in side VirtualBox. Please understand that I cannot keep track of all the latest changes in VirtualBox and Ubuntu 16.04. Therefore, please do not be surprised if things don't look exactly the same as the figures or text on this web page. If you have questions, please feel free to send e-mail to the instructor.

During installation, if something is not working, please check the bottom of this web page and see there is already a known solution to your problem on your system.

Installing VirtualBox should be pretty straight-forward. Just visit the VirtualBox Download web page and download and install the latest stable release (please do not waste your time on experimental releases). In case the latest stable release doesn't work for you, please go to the older builds of VirtualBox web page and download and install VirtualBox 6.1.22 (which is known to work on Windows 10 and Mac OS X).

Click and download VirtualBox for the type of machine/host you have and follow the on-screen instructions to install VirtualBox onto your machine. (The terminology is that if you are running Windows 10, you have a Windows Host; if you are running on Mac OS X, you have a Mac Host.) Below are the typical steps you will see. It may be the case that you are not seeing the same screens since our machines may not be configured the same way. You should typically stick with the defaults, unless you are very familiar with VirtualBox know what you are doing.

  1. Welcome screen: just click on the Next button.
  2. Custom Setup screen (select features): just click on the Next button.
  3. Custom Setup screen (choose options): just click on the Next button.
  4. Warning about Network Interfaces screen: just click on the Yes button.
  5. Ready to Install screen: just click on the Install button.
  6. If you get a screen asking you about permissions, please give permission to install VirtualBox.
  7. Installation Complete screen: just click on the Finish button.
The next thing to do is to install 32-bit Ubuntu 16.04 into VirtualBox.

You have two choices. You can either installed a pre-canned 32-bit Ubuntu 16.04 system by following the instructions below. Or, you can install a 32-bit Ubuntu 16.04 system from scratch. The first method saves a lot of time, and therefore, is preferred for this class. With VirtualBox is that you can install as many virtual machines as you'd like. You can use the second method to gain experience in installing virtual machines from scratch when you have extra time. It would look good on your resume! For now, you should use the first method.

The easiest way is to install a pre-canned 32-bit Ubuntu 16.04 system from a virtual appliance called "md32xu16047eolvm-vbox6118-f1". There are two places from which you can download this virtual appliance: First, you need to download this virtual appliance Save the downloaded file as "md32xu16047eolvm-vbox6118-f1.ova". This file is about 3.5GB in size and it can take a while to download. If you have a poor Internet connection, it may take over an hour to download this file! Once you have downloaded this file, you should not delete it because you may need it again if one day your system refuses to boot (trust me, this can happen).

When you are done with installing VirtualBox, your machine would launch VirtualBox automatically and you will get a screen that looks like the following:

If you click con About VirtualBox under the Help Menu, you will see the version of the VirtualBox you are running. The screenshots here are from VirtualBox-6.1.6. If you are using a newer version of VirtualBox, your screens may look different and some of the default values may be different.

Step 1: Import Virtual Appliance

Click on the Import button and your screen will look like the following:
Click on the yellow folder icon on the right to select a virtual appliance. Select the "md32xu16047eolvm-vbox6118-f1.ova" file you have just downloaded and your screen will look like the following (please note that the photo is a bit old and the strings on the screen will not match what you see and that's okay)):
Click on the Import button at the bottom and it will start importing the virtual appliance. It can take a few minutes to finish importing. When you are done, your screen should look like the following (if the right side looks different, it's perfectly fine):
The most important two buttons on the right are the Settings button and the Start button. The most important setting is the setting for the Display. For now, just click on the Settings button and you will get a popup window. In the popup window, click on Display on the left and you will see a screen that looks like the following for the Display setting:
Don't click on anything! I just want you to see the checkbox that's labeled, "Enable 3D Acceleration". This is a very important checkbox! In the above screenshot, it's showing that this checkbox is currently checked. If things go wrong, you might want to come back here and uncheck this checkbox and try again! For now, keep it checked because it will make your virtual machine run faster.

If your host machine is running Mac OS X, another important setting in the above screen is the amount of video memory your virtual machine gets. In the above screenshot, it's showing that your virtual machine will be given 16 MB of video memory. If things go wrong, you might want to come back here and set the video memory to 128 MB and try again.

Another important setting is the setting for the "base memory". Click on System on the left and you will see a screen that looks like the following for the System setting:

Don't click on anything for now! I just want you to see that "Base Memory" is set at 1024MB (i.e., 1GB). You should run as few things inside your virtual machine as possible because things are slower when you run them inside a virtual machine. For example, if you want to use a web browser, it's best that you run your web browser on your host machine and not inside the virtual machine (unless there is a good reason for it). If you must run many applications inside your virtual machine, you can give your virtual machine more memory by changing the Base Memory setting here. Please understand that the more memory you give to your virtual machine, the less memory your host machine will be left with! So, you need to first figure out how much memory your host machine has. I think it's a good rule that Base Memory should never exceed 1/3 of the total amount of memory of your host machine. For now, keep the Base Memory at 1024MB.

Now click on the Cancel button to go back to the start screen and proceed to start your virtual machine.

Step 2: Start Your Virtual Machine

Now your 32-bit Ubuntu 16.04 system is ready to go! The name of your system is "md32xu16046vm-vbox616". It means "MyDesktop 32-bit XUbuntu 16.04.6 VM (created on VirtualBox 6.1.6)". All you need to do is to click on the Start button to boot up your 32-bit Ubuntu 16.04 system. So, go ahead an click on the Start button (looks like a green arrow in the above screenshot). It can take several minutes for your system to boot. Be patient.

If all goes well, you will see the following screen (this is the XUbuntu Desktop):

The above screenshot is from a Windows machine. If you have a Mac, then the screen will of course look different (for example, the menubar will be on the very top of your screen, just like for all Mac applications). On some systems, you will get a popup window saying something about an "Indicator Plugin", just click the Remove button.

If you don't see the above screen but get a black screen instead, then you need to trouble-shoot to figure out what's wrong. If you get a black screen, you should first turn off the virtual machine. Since you were not able to start Ubuntu 16.04 successfully, you must do a forced shutdown of your virtual machine. If you are on Windows, you should click on the Close Box as shown in the screenshot above. You will get a popup window asking if you want to "save the machine state", "send the shutdown signal", or "power off the machine". At this time you must select "power off the machine" and click on the OK button. Wait for the virtual machine to completely shutdown (i.e., when the virtual machine window disappears) before proceeding to trouble-shoot. This can take some time, so please be patient. After the virtual machine has completely shutdown, the first thing you should try is to uncheck the Enable 3D Acceleration checkbox and restart and hope that you will get a better result! If you don't, you should contact the instructor.

If all goes well and you got the XUbuntu Desktop, please click on the Terminal program and your screen should look like the following:

You are logged in automatically by default. Your user ID is "student" and this is an administrator account. Your password is also "student". Please note that this is also your administrator password! Any time you are prompted for the "admin password", you should enter this password.

Your default commandline shell is "bash". If you want to switch to use "tcsh", you can just type:

    tcsh
and you should see that your commandline shell prompt will look different.

Once in a while, you will get a popup window asking you to update your system, please just cancel the popup window! If you really want to update your system, all you have to do is to type the following in your commandline shell:

    upgrade
You will be prompted for the admin password. You should enter your admin password and proceed with updating your system. (Please note that this command is called "upgrade", but it doesn't really "upgrade" your system. It updates your system.)

One more thing to try before proceeding... Maximize the window of your virtual machine and see if the size of the Ubuntu desktop would fill the virtual machine window. If the Ubuntu desktop size doesn't change, you should first install Guest Additions before proceeding. If the Ubuntu desktop resizes automatically, it means that you have Guest Additions already installed (which only needs to be done once).

Step 3: Set Up Shared Folder

It's very useful to be able to exchange files between your virtual machine and your host machine. The way to do it is to use a shared folder. To setup a shared folder, you need to first shutdown your virtual machine. The proper way to shutdown your virtual machine is to click on Main Menu in the XUbuntu Desktop. You will get the following screen (which is the main Xbuntu Menu):
From this screen, you can find a lot of programs to run. For now, just click on the Power off button in the lower right corner and you should get the following screen:
Click on the Shut Down button to shutdown your virtual machine and go back to the VirtualBox start screen. If for some reason this doesn't work, you can also do the following. Start a Terminal and simply type the following:
    halt
Click on the Settings button and then follow the instructions to set up a shared folder. To match what's already set up in your pre-canned virtual machine, please make sure to enter "/Shared-ubuntu" as your "Mount point" when you set up your shared folder and make appropriate adjustments. After this is all set up, when you run your Terminal program, you can access the shared folder using the "Shared-ubuntu" folder in your home directory. By the way, shared folder can only work if you have installed Guest Additions.

If you get an error when accessing your shared folder, please try this fix and see if it works.

Once your Ubuntu 16.04 system is running smoothly, you should never need to shutdown your virtual machine again! Whenever you need to shutdown your virtual machine, you should just suspend it. On Windows, you can simply click on the Close Box and select "save the machine state" to suspend your virtual machine. If you do it this way, next time when you need to start your virtual machine, just click on the green Start button in VirtualBox and your virtual machine state will be restored and this is much faster than cold-booting your virtual machine.

Step 4: Backup Files You Have Created

Since it can take a while for your virtual machine to start, I would recommend that you do not shut down your virtual machine! If you simply close the lid of your laptop, everything will go to sleep, including your virtual machine. Although if you let your laptop battery run out, your virtual machine would crash when your laptop dies. Most of the time, no harm is done when this happens. Although I have heard from students that when you are unlucky, you may not be able to get back into your virtual machine! When this happens, as far as I know, there is no way to recover the data inside your virtual machine! Therefore, it's imperative that you backup files you have created by copying them out of your virtual machine and into the shared folder and use your host machine's backup software to backup your shared folder. It's also a good idea to not overwrite files you have previously backed up (or use a version-control system) in case you need to get back to some older versions of your files.

To make backup easy, you should put all your files in one place. For example, you can do all your work somewhere under the Documents folder in your home directory. Then you can do the following to create a backup file and copy it into your shared folder using the following commands:

    cd $HOME
    tar cvzf Shared-ubuntu/Documents-backup-`date +%d%b%Y-%H%M%S`.tar.gz Documents
The above command assumes that you have already setup a shared folder in the Shared-ubuntu folder in your home directory. Please do not type the above command by hand! Just copy the above two lines and paste into your Terminal. (If you get a "cannot open" error when you tried the last command, please try this fix and see if it would help.)

Another way (probably a more cumbersome way) is to use your Google Drive to backup your files from within the virtual machine. In this case, you will need to start your browser and login to your Google Drive and then upload your files. No matter which way you choose, it's extremely important that you have a backup strategy and have a good habit of backing up files you have created at least once a day.

Step 5: Run Your VirtualBox Headless

This is totally unnecessary. But if you really want to run your VirtualBox "headless", i.e., without a desktop user interface, please read on (and I will assume that you are an Linux expert). Otherwise, you are done and you don't need this step.

Shutdown Ubuntu 16.04 and do the following (this is a quick summary of this website):

  • Click on Settings, then Network.
  • Under Adapter 1, click on Advanced, then Port Forwwarding.
  • Click on the "+" icon to add an entry and enter SSH under Name, TCP under Protocol, 127.0.0.1 under Host IP, 5679 under Host Port, 10.0.2.15 under Guest IP, and 22 under Guest Port, then click on OK to finish creating this entry.
  • Click on Adapter 2, click on Enable Network Adapter, select Host-only Adapter for "Attached to", and select vboxnet0 or VirtualBox Host-Only Ethernet Adapter for "Name", then click on OK to finish setting up Adapter 2. (If nothing is available select under "Name", please take a look at this web page and go to 'File', then Host Manager, then press Create to create a host network with the specified IP address above.)
  • Click on System and check the Network checkbox in Boot Order and check the Enable I/O APIC in Extended Features.
  • Click on OK to finish Settings then start your Ubuntu 16.04 system.
In Ubuntu 16.04, start a Terminal and run the following command to install the OpenSSH Server:
    sudo apt-get install openssh-server
After you the OpenSSH Server is installed, run the following command:
    ifconfig
and you will see a printout that looks like the following, showing all the "interfaces" of your Ubuntu 16.04 system:
    enp0s8    Link encap:Ethernet  HWaddr 08:00:27:85:b3:3c  
              inet addr:192.168.56.102  Bcast:192.168.56.255  Mask:255.255.255.0
              inet6 addr: fe80::751b:b7d0:e668:1eca/64 Scope:Link
              UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
              RX packets:1 errors:0 dropped:0 overruns:0 frame:0
              TX packets:40 errors:0 dropped:0 overruns:0 carrier:0
              collisions:0 txqueuelen:1000 
              RX bytes:590 (590.0 B)  TX bytes:5560 (5.5 KB)
    
    lo        Link encap:Local Loopback  
              inet addr:127.0.0.1  Mask:255.0.0.0
              inet6 addr: ::1/128 Scope:Host
              UP LOOPBACK RUNNING  MTU:65536  Metric:1
              RX packets:28 errors:0 dropped:0 overruns:0 frame:0
              TX packets:28 errors:0 dropped:0 overruns:0 carrier:0
              collisions:0 txqueuelen:1000 
              RX bytes:1893 (1.8 KB)  TX bytes:1893 (1.8 KB)
The important part is highlighted in red. The above is showing that my Ubuntu 16.04 system has two interfaces. The "lo" interface is to be used internally (i.e., from withint Ubuntu 16.04) and the other interfaces may be suitable for you to ssh into. In my case, my only choice is the enp0s8 interface which has an "inet addr" (i.e., IP addres) of 192.168.56.102. Therefore, if I want to ssh into this machine, from outside of this virtual machine, I should do:
    ssh student@192.168.56.102
Once you have verified that this works, you can shutdown your Ubuntu 16.04 system. Next time you start Ubuntu 16.04, instead of just click on the green Start button, click on the drop-down menu on the right side of the green Start button and select "Headless start". You can watch the Preview window to estimate if your Ubuntu 16.04 system is up and running or not. Then try the above ssh command. Please remember that you don't have a desktop user interface any more!

Finally, where can you ssh from? You need a commandline app. On Mac OS X, you can run a "terminal" program. On Windows 10, you can run a PowerShell, or you can download putty (just google "putty download"). Please note that if you want to run a program on Ubuntu 16.04 that has a graphical user interface, then you need to run an X11 server on your host machine. If your system is an Mac OS X system, you can install XQuartz and if your system is running Window 10, you can install X-Win32 from ITS software website. Please note that if you get X-Win32 from ITS, you need USC VPN in order to run X-Win32. If you don't want to run USC VPN, another choice for Windows 10 is Cygwin (although it's kind of an overkill since it's a full-blown Linux-like system).