Virtual Machine for CSc 103

Installation

Download and install VirtualBox (choose the option corresponding to the operating system installed on your computer; VirtualBox will then enable you to run any other OS inside it). Note: it is safe to keep all of the defaults for installation. If you are having trouble, there are more detailed instructions on the site.
Download the virtual machine image. If your browser asks you what you want to do with the file, just save it – don’t try to open it yet. NOTE: The file is around 1GB, so it might take a minute!
To install the virtual machine, use the File..Import appliance menu, or just hit Ctrl-I. The steps are simple, and it is safe to keep all of the defaults, although you might want to give the virtual machine more than 1GB of RAM if you can spare it.
Make sure the virtual machine is working: select it from the list on the left and hit “start” from the menu, or just hit enter, or double-click it. This should start the OS in a new window. If anything goes wrong, try following the troubleshooting section below.
Hopefully you will see a login prompt at this point. Enter csc103 for the user name and the password (note: no characters will be shown when you type the password, but don’t worry, it is working!).
You should soon find yourself looking at something resembling a computer desktop environment. If not, you might want to check that the download completed properly. To do this, check the SHA-256 hash by running `sha256sum arch-ccny-103.ova and making sure that the output is:
```
 3c6dda41688cee34dae5586bc4031dd88fc5b677714be4714e2858382445b1c3
```

Notes

Getting Started

Hopefully the interface is familiar enough that it will not need much explanation. One common thing you’ll want to do is open a terminal, which can be done with alt+enter. Your window key (option on a mac?) will also bring up a menu where you can search for programs.

One important note: do NOT just close the virtual box window while the system inside is running. This might leave files half-written and give you trouble. Instead, use “Shut Down” from the menu (lower left corner).

Other Remarks

You can tab complete commands and file names! You should rarely have to type out every character of a command.
If the window containing the virtual machine needs resizing, maybe use full-screen mode, or the menu “view…auto-resize guest display” combined with manual resizing of the window.
Sometimes keys (e.g. the shift key) get “stuck” after moving from the virtual machine back to the regular OS. This can usually be avoided by using the mouse to switch to and from the VM window (instead of alt-tab). If a key does get stuck, random button mashing might actually be the answer. Just do it somewhere safe!
Your command prompt is in “vim mode”. If you press escape while typing a command, you will be able to navigate what you’ve typed so far using vim commands. This is great if you know vim, but could be frustrating if you don’t, and have accidentally hit escape! If this happens (you’ll see that your terminal prompt starts with a : instead of a +), then just hit escape a few times to be sure, and then press A and normalcy should be restored.

Tiny font on high resolution displays

Depending on your screen, you might find the font in the virtual machine too small to read. This might be fixable through the “scale factor” in the VirtualBox settings. (On the main VirtualBox screen, open the settings for our virtual machine. Under “Display”, there is a “scale factor” setting that you can increase.) Get in touch with me if this still does not suffice and we can increase the font size for various applications.

It may be desirable to share data between your operating system and the virtual machine. This is easily accomplished by any of the following, in descending order of preference.

If you just want to backup and transfer your source code for the projects and such, I’d recommend pushing your repository to a remote server. Bitbucket or github are a good choices for repository hosting.
Use ssh and scp.
Make a shared folder using virtual box. There are instructions online, but it is very simple. In the main virtual box window (the one that shows before you boot the guest OS), go to settings..shared folders, and add a folder from your hard drive. Then boot the VM, and run
```
  $ mkdir -p ~/host && sudo mount -t vboxsf -o uid=csc103 shared ~/host
```
where shared is the name of the shared folder you set up (the name you supplied to virtual box). Then ~/host will be the folder on the VM that serves as the mount point. If the command is successful, then ~/host/ will point to the folder you’re sharing from your own OS.
Make backups and transfers using a USB device.
Email yourself.
You can in fact export the entire virtual machine; see the menu “File..export appliance” from the main virtual box window.

Getting Started with Linux

Here are a few references you might find useful if you haven’t used linux / unix much.

Advanced Configuration + Troubleshooting

If you get an error along the lines of “hardware acceleration not available on your system”, then virtualization might not be enabled in your system’s BIOS. As of 2020, enabling this setting seems often necessary. For windows, I have been able to solve some students’ problems by following the advice in this thread which makes use of this answer.¹ Lastly, you might find this article or this one helpful for finding the right settings if you haven’t been through your BIOS much. Also, some students have found this video helpful on Windows.
If you can’t seem to connect to the internet, even though your actual computer is connected, it might be a DNS issue. (You might see a message along the lines of “could not resolve host”.) First try this:
```
$ sudo systemctl enable dhcpcd
$ sudo systemctl start dhcpcd
```
And if that doesn’t work, I prepared some hard-coded DNS servers which might fix the issue. Try this:
```
$ sudo cp ~/setup/resolv.conf /etc/resolv.conf
```
If you see an error on MacOS about “Installation Failed”, perhaps try this link.
If you find (again on MacOS) that the virtual machine is instantly killed the moment you click away from it (say, to another window on your computer), maybe try this link (search for “input monitoring” and you will find the answer in a reply).
You might be able to resolve video issues (e.g., a black screen after logging in) by increasing the video memory, and perhaps enabling 3d acceleration.
If you need to adjust the amount of RAM allocated for the virtual machine, it can be done through the menus “Machine .. settings .. system .. motherboard”.
You might be able to speed things up by enabling 2d acceleration in the virtual machine settings.
The username and password of the main account are both csc103 if you ever need them. This is also the root password.
If you get a strange error along the lines of “Failed to acquire the VirtualBox COM object:NS_ERROR_INVALID_ARG”, perhaps try this thread.
Some students have found that keystrokes will randomly repeat (you type one f and sometimes get fffffffffff) in addition to seeming laggy. If this is happening on a mac, maybe check out the advice here. You can also try running the command xset r rate 500 20 and see if that doesn’t help (the first number is the delay before autorepeat starts; the second is the number of times it will repeat per second). You can also turn off autorepeat for keys entirely by running xset r off. If you find settings that work you can make them permanent by either editing the xset line in the file ~/.xinitrc, or by running this in your terminal: sed -i 's/^xset.*$/xset r rate 500 20/' ~/.xinitrc.

Maintenance (Optional)

If you want to continue using the virtual machine long-term, it is important to keep the system up to date. Here are some guidelines.

Updating Software

Every week or so, I would recommend performing an update of all software on the system. The command to do so is

$ sudo pacman -Syu

Usually you can just say “yes” to everything and it all goes smoothly. Maybe take these steps in case you encounter trouble:

Check the Arch Linux News page and see if they mention anything about an update requiring “manual intervention”. It is rare, but it might happen once per year with programs you have installed. They will almost certainly have a solution you can follow there.
If you don’t find anything on the news page, then maybe the issue is specific to you. Check the bulletin board and see if anyone is going through the same thing. If you can’t figure it out after some looking around, you can of course ask a question there. Maybe check their guidelines before posting.

Installing New Software

If you want a package that is not installed, probably the best thing to do is find it on the Arch Wiki and follow the instructions there (maybe just include “arch wiki” in your normal internet search). For completeness (and in case what you want doesn’t have a wiki entry), here’s how it works in general. Let’s say we want to install gnunet. First, find the name of it using pacman -Ss:

$ pacman -Ss gnunet
community/gnunet 0.14.0-1
    A framework for secure peer-to-peer networking
community/gnurl 7.72.0-1
    fork of libcurl, which is mostly for GNUnet

It’s the first one, and the package name is simply gnunet. We then can install with sudo pacman -S:

$ sudo pacman -S gnunet

This will automatically install all the dependencies that are needed as well. See man pacman for more information.

Saving Disk Space

The package manager saves old package files just in case you need them, but usually you don’t. It might be a good idea to remove the old stuff now and then (found in the directory /var/cache/pacman/pkg/). You can do this from pacman as well:

$ du -sh /var/cache/pacman/pkg/
4.2G    /var/cache/pacman/pkg/
$ sudo pacman -Sc
Packages to keep:
  All locally installed packages
  ...
:: Do you want to remove all other packages from cache? [Y/n] y
removing old packages from cache...
  ...

$ du -sh /var/cache/pacman/pkg/
587M

Back to the class homepage

Make sure you run those commands “as administrator” and note that it will give you a new boot entry each time you restart your computer. Booting using the new entry will let you run the virtual machine. If you want to just have the default boot entry allow you to use the virtual machine, run the command from this answer.↩︎