The csenv course appliance provides a self-contained 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. The csenv appliance is an alternative to SSH access to the to the CS GNU/Linux machines for working remotely on your own computer.

Contents

• Requirements
• Installation
• Use the Appliance
  • Screen Lock
• Startup and Shutdown
• Pause and Resume
• Troubleshooting
• Software and Licenses

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 3.5GB 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. 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.”)
   • macOS may require this extra step, depending on version.
2. Download csenv-s20.ova [about 3.5GB] 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 csenv-s20.ova has finished downloading, start VirtualBox and choose the menu item File > Import Appliance….
5. Click the folder icon and browse to select csenv-s20.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. Within the appliance, you may be prompted to update the Linux Ubuntu operating system. Do not update Ubuntu! It’s important that everyone in class be using the same default version of Ubuntu (18.04).
10. 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%.
11. Optionally, remove the csenv-s20.ova file from your computer to save space.
12. 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 csenv-s20.

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.

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).

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 csenv-s20.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:

• the Ubuntu distribution of the GNU/Linux operating system
• the VirtualBox Guest Additions
• CodeTub
• several programming tools