The wx appliance is a virtual machine that provides all the software tools for CS 240. You can run the appliance as an application alongside others on your own computer with minimal fuss.

Contents

Purpose

The wx appliance is provided for those who wish to work on their own computers without installation headaches, low-level system incompatibliity, or trouble with remote access. Using the appliance is not required. Physical CS Linux machines are always available in the microfocus or S173.

The wx appliance has all the tools you need and is isolated from the rest of your computer. No need to mess around with temperamental installers, find that things don’t work, or possibly break things directly on your computer. Plus you have a GNU/Linux environment and virtual machine available on your laptop any time you want to tinker or learn more.

Regardless of what machine you use, working in the microfocus or S173 labs is great for class camaraderie! (And you might even get some great tips from peers, or your instructor, whose office happens to be close by.)

Caveats

Infrastructure described in this document is still a bit experimental. If your wx appliance stops working, you can replace it easily with a new one, but you might lose all the files you stored on the old one. That means you should backup anything of importance stored on your appliance. Luckily, this is pretty easy if you are using version control to manage your work as we do in this course.

Requirements

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

  • a fairly recent 64-bit Intel or AMD x86 processor;
  • 4GB or more of RAM (as little as 2GB may work with some tweaking);
  • Mac OS X 10.8 or later, Windows Vista SP1 or later, or any recent major distribution of GNU/Linux; and
  • 5-6GB of free disk space

Installation

  1. Download wx-s17.ova [~1.9 GB] to your computer. This will take a while. Do it on the campus network.

    Alternatively, use scp to get the file if you have a CS account and scp installed (allows access from anywhere, not just campus):

     $ scp your_username@cs.wellesley.edu:~bpw/public_html/wx/s17/appliance/wx-s17.ova .
  2. While you are waiting, download and install the latest version of VirtualBox 5.
  3. Once wx-s17.ova has finished downloading, start VirtualBox and choose the menu item File > Import Appliance….
  4. Click the folder icon and browse to select wx-s17.ova, then click Continue.
  5. Click Import to accept the default machine parameters. This will take a few minutes.
  6. In the VirtualBox manager application, select the appliance on the left and click the Start button (green arrow) to start up the appliance.
  7. Once you are sure the VM started successfully, you can remove the downloaded wx-s17.ova file to save space.
  8. Continue to the next section.

User and Initial Setup

The appliance has one user, named wx, that is logged in automatically on startup. The first time the appliance is started, it will automatically run a script that asks you a few questions to get you setup for remote CS access, Bitbucket accesses, and specific courses.

The wx user’s password is wx. When the setup script is done, change the password for security: Open a new terminal and run the command passwd. (We removed fancy GUIs for these sorts of things to save space since you won’t need them much.)

If you have successfully installed and started using your copy of the wx appliance, you can safely delete the wx-s17.ova file that you downloaded.

Startup and Shutdown

The wx appliance can be started and shut down much like a physical computer. It can also be paused. Read the VirtualBox manual to learn how to control it and how it interacts with your mouse and keyboard.

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

Shut down the appliance by clicking the wx menu in the upper right corner of the appliance screen and choosing Shut down.

Do NOT choose Power Off Machine or Reset from the VirtualBox VM Application!

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. (Notice the lightning bolt next to that option!) Students who do this end up with corrupted Mercurial repositories. The Send the shutdown signal option is OK. This asks the wx appliance to shut itself down.

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 by clicking to close the VirtualBox VM window holding the wx screen. Choose Save the machine state and click OK. VirtualBox VM will take a few seconds to save the wx appliance’s current state, then it will close the wx appliance. The listing for the wx appliance in the VirtualBox manager will now show it as Saved (vs. Powered Off). This is like stopping time, and is similar to sleeping/hibernating.

Pause the wx appliance

Resume an appliance whose state has been saved the same way you start an appliance.

Use the Appliance

Common applications appear in the upper left corner. The leftmost icon is a menu providing access to all GUI applications.

More documentation: The wx appliance uses the Fedora Xfce spin distribution of the GNU/Linux operating system, including the XFCE destop environment. We have removed some non-essential software packages from the default distribution and installed programming-related packages.

Host-Guest Integration

The wx appliance comes with extensions installed in the guest operating system to support some useful features such as:

  • a clipboard that is shared between the host (the software on your personal machine) and the guest (the software running in the wx appliance)
  • shared folders that appear in both the host and guest
  • drap-and-drop may also be supported in some cases.

Check the Devices menu in the running VirtualBox VM application to enable or disable these features.

Read the VirtualBox manual for more information.

Updates

From time to time, we may need to install new software or make changes to your copy of the wx appliance. We will let you know when this is needed. To get updates, run sudo dnf update in a terminal. This may prompt for your wx password.

Under the Hood: Software and Licenses

The wx appliance is currently available only to students, faculty, and staff within Wellesley College.

The wx appliance uses a mix of free software and open-source software, plus a couple management tools of our own design that will eventually be released under such licenses.

We use VirtualBox (manual) to package and execute the wx appliance.

The wx appliance is based on the Fedora 23 GNU/Linux distribution with the XFCE desktop environment. We have removed some non-essential software packages from the default distribution and installed several programming-related packages.

Troubleshooting

Please report issues to Ben Wood. Detailed descriptions and any troubleshooting you have tried (or solutions you have found) are useful.

Network Trouble: “Could not resolve hostname”

Symptoms: If you have trouble connecting to network services (e.g., when trying to hg push some commits), your wx 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), but your wx appliance does not notice that the network has returned.

You can confirm this issue by checking that (a) your computer has network access and (b) your wx appliance does not. In the wx appliance screen, check the “two screens” icon in the upper right. If it has a red X, it is disconnected from the network.

  • Connected:
  • Disconnected:

Solution: In the VirtualBox VM application (the one that displays the wx appliance screen), first disconnect the virtual network adapter, then reconnect it. There are two ways to access this option:

  • Click the tiny “two screens” icon in the lower right status bar of the VirtualBox VM window.
  • OR: Choose the Devices > Network Adapter menu in the VirtualBox VM menu bar.

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

“VT-x” or “AMD-V” Unavailable or Disabled

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

Solution: “VT-x” and “AMD-V” are Intel and AMD’s special hardware support for efficient virtual machines. 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 machines. You’ll need to change a low-level setting outside the operating system to enable hardware support for virtualization. It is fairly straightforward.

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

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

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

More reference here and here.

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