Link Search Menu Expand Document

Virtual machine setup

Table of contents

  1. Vagrant troubleshooting
  2. Windows troubleshooting
    1. Windows Subsystem for Linux (WSL)
    2. SSH client
    3. Bootup timeout
    4. Hyper-V

We have prepared a virtual machine image that is preconfigured with all the development tools necessary to run and test your code for this class. Later in the course, we will discuss virtual machines; for now, you can think of it as a software version of actual hardware.

If you are unable to use an x86-based VM (notably Apple M1 Macs), or would prefer not to set up a local development environment, you can use instructional machines or do a cloud setup. See the “Instructional Machine Setup” and/or ”Cloud Setup” section for details. We recommend using instructional machines since they are significantly easier to set up.

Vagrant is a cross-platform tool for managing virtual machines. You can use Vagrant to download and run the virtual machine image we have prepared for this course. (The virtual machine for the course is different every term. Do not use one from a previous semester.) Vagrant depends on providers for virtualization. The default provider is VirtualBox, an open-source virtualization product.

First, download and install the latest version of VirtualBox from the VirtualBox website. We recommend using the latest version of VirtualBox, as certain earlier versions of VirtualBox (6.0.0 - 6.0.4) may not properly boot our class VM. Alternatively, for some users, VirtualBox 5 is more stable than VirtualBox 6.

Next, download and install the latest version of Vagrant from the Vagrant website.

After Vagrant and VirtualBox are installed, type the following into your terminal to initialize your VM and begin an SSH session:

mkdir cs162-vm
cd cs162-vm
vagrant init cs162/summer2022
vagrant up
vagrant ssh

These commands will download our virtual machine image from our server and boot it. The download of the image will take a while, and requires an Internet connection.

From the cs162-vm directory you created earlier, you can run vagrant up to start the virtual machine, and vagrant halt to stop the virtual machine. To start a SSH session to the virtual machine, run vagrant ssh. You can run exit to exit an SSH session.

Vagrant troubleshooting

After running vagrant up, you may run into an error reading The IP address configured for the host-only network is not within the allowed ranges. This can be fixed on macOS and Linux with

sudo mkdir -p /etc/vbox
sudo sh -c 'printf "* 10.0.0.0/8 192.168.0.0/16\n* 2001::/64" >> /etc/vbox/networks.conf'

This appends the lines outlined in this Stack Overflow post to the file, so avoid running the command multiple times. If you would like to overwrite the contents of the file (i.e. you don’t care about the existing contents), you can replace the second command with

sudo sh -c 'printf "* 10.0.0.0/8 192.168.0.0/16\n* 2001::/64" > /etc/vbox/networks.conf'

If vagrant up still fails, try running vagrant provision and see if it fixes things. As a last resort, you can run vagrant destroy to destroy the VM. Then, start over with vagrant up.

Note: Some shells may have issues with escaping newlines. Check that your /etc/vbox/networks.conf file ends in something like this (the asterisks are necessary):

* 10.0.0.0/8 192.168.0.0/16
* 2001::/64

You can also edit the /etc/vbox/networks.conf yourself if necessary, using vim, emacs, or another text editor.

Windows troubleshooting

Windows Subsystem for Linux (WSL)

We do not recommend using Vagrant and/or VirtualBox in WSL. If you choose to use Vagrant for Linux inside WSL, you should still have VirtualBox installed in Windows. Vagrant has documentation on the configuration necessary to support usage of Windows VirtualBox inside WSL.

SSH client

On the latest version of Windows 10, the virtual machine should work on the default command line. If you are using an older version of Windows, your installation may not support SSH from the command line. In this case, the “vagrant ssh” command from the above steps will cause an error message prompting you to download Cygwin or something similar that supports an SSH client. Previous TAs have wrote a guide on setting up Vagrant with Cygwin in Windows. Alternatively, it is possible to use PuTTY instead of Cygwin.

Bootup timeout

If you get an error about your VM bootup timing out, you may need to enable VT-x (virtualization) on your CPU in BIOS.

Hyper-V

If you get an error about Hyper-V being enabled, you should disable Hyper-V to use VirtualBox. Alternatively, you can set up Vagrant to utilize Hyper-V as the provider instead of VirtualBox, and create the VM yourself (see CS 162 VM provisioner above for details).