Course Appliance

The * course appliance* provides a self-contained CS 240 computing environment as a virtual machine that you can run alongside other applications on most personal computers. It is isolated from the rest of your computer and independent from the CS workstations. The appliance is an alternative to SSH access to the to the CS GNU/Linux machines for working remotely on your own computer.

Contents

Requirements

Most computers from the last 5 years or so should suffice. You need a computer with:

  • one of these operating system versions
  • a fairly recent 64-bit Intel or AMD x86 processor;
  • 4GB or more of RAM (2GB could work, but it would be tight);
  • 12GB of available storage (disk) space:
    • about 3GB for the download (can be deleted after installation)
    • about 8GB for the installed appliance

You are responsible for backing up any data of importance stored on your appliance. This happens naturally if you employ good version control practice on your work.

Installation

Use these directions to install the course appliance on your computer. CS 240 staff will provide support if you have issues.

  1. Download and install the latest version of VirtualBox 6.1. (DO NOT download or install the “extension pack.”)
  2. Download -f20t1.ova [about 3GB] to your computer. This will take a while depending on the speed of your connection.
  3. While you are waiting, read about how VirtualBox captures your mouse and keyboard input and how to release them with the host key.
  4. Once -f20t1.ova has finished downloading, start VirtualBox and choose the menu item File > Import Appliance….
  5. Click the folder icon and browse to select -f20t1.ova, then click Continue.
  6. Click Import to accept the default machine parameters. Importing will take a few minutes.
    • If your physical computer has only 2GB of RAM, try adjusting the appliance to use 768MB or 1024MB of RAM at this step.
  7. In the VirtualBox manager application, select the appliance on the left and click the Start button (green arrow) to start up the appliance.
  8. When the appliance has started, you should see its desktop environment.
  9. If text/icons in the appliance window are too tiny: In the VirtualBox manager application, select the appliance and click the Settings button (orange gear). Select Display and raise the Scaling Factor, perhaps to 200%.
  10. Optionally, remove the -f20t1.ova file from your computer to save space.
  11. Complete the account setup instructions once.

Problems? see the Troubleshooting section.

Use the Appliance

The appliance automatically logs in as the user u. This account is local to your appliance. It does not share storage or preferences with your CS account. Use version control or scp to transfer files between them.

The appliance presents a fairly minimal interface, focused on a few relevant programming tools.

  • Left side: tools, including Emacs, terminal, file browser, help, all applications (lower left)
  • Upper right: clock, network status, shutdown

The appliance should already contain all necessary software. If you need to install additional software or make system changes, the u user has admin permissions. The password is ucandoit.

Screen Lock

If the csenv appliance remains inactive long enough while running, it will lock its screen. You can unlock it with the password above.

You may also wish to disable the Screen Lock. To do so, click the settings icon (in the dock at the left of the screen), find the Privacy section, and click the Screen Lock line, which will give you the option to turn it off.

Startup and Shutdown

Start up the appliance: open VirtualBox, select the appliance in the list on the left, and click the Start button. This launches a separate application running the appliance.

Shut down the appliance: click the icons in the far upper right corner of the appliance screen, click the power button symbol, then click Power Off.

Do NOT use Power Off Machine or Reset!

These options are equivalent to yanking out the battery or power cord while the computer is running or holding down the power button to hard reset. These tend to result in corrupted files. It is OK to Send the shutdown signal, which asks the appliance operating system to shut itself down gracefully.

Do NOT 'power off' the appliance!

Pause and Resume

Pausing and resuming the appliance is convenient if you want to keep some windows open in the appliance but you want to free up resources on your computer while you work on something else.

Pause the appliance: click to close the VirtualBox VM window that contains the appliance display. Choose Save the machine state and click OK.

VirtualBox VM will take a few seconds to save the appliance’s current state, then it will close the appliance. The listing for the appliance in the VirtualBox manager will now show it as Saved (vs. Powered Off).

Pause the appliance.

Resume the appliance: select the appliance in the list on the left and click the Start button.

Troubleshooting

If the following suggestions do not help, please report issues to your instructor. Detailed descriptions and any troubleshooting you have tried (or solutions you have found) are useful.

On macOS: VirtualBox Installation Failed (or Kernel Driver not Installed)

Symptom: Installation of VirtualBox fails for unspecified reason or because “Kernel Driver not Installed”.

Solution: [New, may need tweaking]

Open System Preferences, go to the Security & Privacy pane, and click the Allow button next to the prompt asking to approve extensions by Oracle, Inc.

If you do not have this prompt, first change the Allow apps downloaded from: option to App Store and identified developers, then try the install again, after which you will need to Allow Oracle as above, and retry.

Network Trouble: “Could not resolve hostname”

Symptoms: Trouble connecting to network services (e.g., with version control operations), typically including “could not resolve hostname.”

Cause: The appliance has likely lost its network connection. This can happen when your physical computer temporarily loses and then regains its wireless network connection (a common occurence at Wellesley). Sometimes the appliance does not notice that the network has returned.

Confirmation:

  1. Check that your physical computer has network access (can you access the web)?
  2. Check that the appliance does not have network access.
    • The appliance screen shows a “two screens” icon in the upper right when connected:
    • The icon includes a red X when disconnected:

Solution: In the VirtualBox VM application (the frame around the appliance display), disconnect then reconnect the virtual network adapter to make the appliance notice the connection.

There are two ways to disconnect/reconnect the network adapter:

  • Click the tiny “two screens” icon in the lower right status bar of the VirtualBox VM window (in the frame around the appliance display, not the icon you just examined in the upper right).

  • OR: Choose the Devices > Network Adapter menu in the VirtualBox VM menu bar.

Uncheck, then re-check the Connect Network Adapter option. After a few seconds, the appliance should reconnect to the network.

On Windows: “VT-x” or “AMD-V” Unavailable/Disabled or “kernel requires an x86_64 cpu, but only detected an i686 cpu”

Symptoms: When trying to start your appliance from VirtualBox, some Windows computers may give an error about “VT-x” or “AMD-V” being unavailable or disabled.

Cause: “VT-x” and “AMD-V” are Intel and AMD’s special hardware support for efficient virtual workstations. If you have a relatively recent computer (last few years), it is likely you have these features, but they may be disabled on some Windows computers.

Solution: You will need to change a low-level setting outside the operating system to enable hardware support for virtualization. It requires changing a low-level setting, but is fairly straightforward.

To enable virtualization support on a computer with UEFI (newer computers):

  1. Hold the shift key while pressing restart to reboot your computer and access the UEFI settings. You should see an interface other than the usual Windows startup. If you do not, try the BIOS directions below.
  2. Select Troubleshoot, then Advanced Settings, then UEFI Firmware Settings.
  3. Find Security or Virtualization Settings (or something similar).
  4. Enable hardware support for virtualization.
  5. Select something to the effect of “save and reset” to save the settings changes and reboot the computer.

To enable virtualization support on a computer with BIOS:

  1. Reboot your computer and hold the F2 or F10 key as it is starting up. This will cause it to enter a mode (known as BIOS or firmware settings) allowing you to set low-level hardware options. (If the first of F2/F10 that you try doesn’t work, try the other. The screen probably tells you which.)
  2. Use the arrow keys to find the Security or Virtualization Settings (or similary named) section, possibly within a Processor or CPU section.
  3. Enable hardware support for virtualization.
  4. Select something to the effect “save and reset” to save the settings changes and reboot the computer.

More reference here and here.

You may need to delete the virtual machine you created in the VirtualBox manager and reimport -f20t1.ova for it to recognize the virtualization support.

Software and Licenses

The course appliance is built from free and open-source software.

The appliance contains installations of: