Virtual Machine for CSc 103

Installation

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

2. 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!

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

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

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

6. You should soon be greeted by a soothing picture, perhaps featuring some trees. If so, rejoice :D Otherwise, you might want to check that the download completed properly. To do this (on a *nix system, including mac), check the SHA-1 hash by running sha1sum arch-ccny-103.ova¹ and making sure that the output is:

    889178027121d4338809603ee0627d561a67754c

Notes

Getting Started

The virtual machine uses a tiling window manager which may take a moment to get used to. Below, I’ve summarized some of the basic commands you’ll need to know to make good use of it. You might also check out this reference card for i3.² You can also see a demonstration video I recorded last year in case that helps. (It’s over an hour long, and I’m not sure how much sense it will make without the twitch chat to go with it, but if you’ve got nothing better to do, maybe give it a look.)

1. To open a program by name, hit alt+d and then start typing the name into the little box that has appeared at the top of the screen. Use the tab key to auto-complete. Try opening firefox this way. (Note: on a Mac, the alt key might be the Option key.)
2. You can close any window with shift+alt+q.³
3. To get a new terminal, just press alt+enter. From the command line, you can use the command $ open [filename] and it will usually figure out the right program to open filename with.
4. You have multiple desktops / workspaces. You can reach them with alt+1,alt+2,alt+3, etc. Try opening firefox in a new workspace (switch to workspace 2, and then open firefox).
5. You can move between windows with or without the mouse. Using the mouse, just move the cursor over the desired window to focus it. Using the keyboard, press alt+<arrow key> for whatever direction you want to move. You can also use alt+ the home row keys j,k,l,; to move left, up, down, and right, respectively.
6. If a window feels too small, you can make it fullscreen with alt+f, or move it to another workspace with say, shift+alt+2 (this moves it to workspace 2).
7. If you want the next window to appear below the current, use alt+v before running the next program. To toggle the container between horizontal and vertical layouts, use alt+e. You can also create a “stack” of windows with alt+s.
8. Try to use Vim. It is so worth it… Just run the command $ vimtutor to get started. There are also some links to tutorials on the course information page.
9. I would recommend using cd, ls, cp, mv, rm and such instead of a file manager, but if you long for that windows explorer feel, try running thunar.
10. Important: To gracefully shutdown the machine, use shift+alt+e, and then press w. Do not just close the virtual machine window! (Closing the window is the equivalent of ripping out the battery from your laptop while it’s running, and may leave the disk in an inconsistent state.) Note also that there is a menu in virtual box (file->close->power off the machine) which sounds good, but should not be used! Use shift+alt+e and then w and you should not have any trouble.

Other Remarks

1. You can tab complete commands and file names! You should rarely have to type out every character of a command.
2. The virtual machine has all the tools you’ll need to build C++ programs, and should give you a pleasant programming experience. Feel free to develop on other platforms if you want, but in that case, help with technical issues may not be forthcoming.
3. Use full-screen mode to get resolution beyond 1024x768. (Something like right-control + f.) If this doesn’t work, see below. (Note: as of September 2020, there are some reports of the fullscreen mode leaving you with a blank window; try manually resizing the window instead if this happens to you.)
4. 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!
5. Copy and pasting in the terminal: If you just highlight text with the mouse in your terminal it will be copied to a clipboard. To paste this into another terminal window, you can use Shift+Insert, or middle click the mouse (if you only have two buttons, try tapping them both at the same time to get a middle click). However, pasting stuff into your terminal can be dangerous as you may end up running an unintended command. Note also that shift+PgUp and shift+PgDn will scroll back through your terminal history.
6. 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.

A E S T H E T I C S

Wallpaper

If you don’t like the wallpaper, you can play wallpaper roulette by pressing alt+shift+w.⁴ If that feels like too much randomness in an already chaotic world, you can check out the alternatives I’ve left using the command

$ feh ~/.config/i3/bkgs/*.jpg

Navigate with the left / right arrows, and if you see one you like you can set it as the background by right clicking and following the menus.

Terminal colors

If you prefer light backgrounds for your terminals, run this command:

$ xrdb ~/.Xresources_light

Then any subsequent terminals you open will have a light color background. To make the change permanent, use this command:

$ cd && ln -sf .Xresources_light .Xresources

If you want to make more drastic changes to the colors, you’ll have to edit .Xresources. You can also change the terminal font and size there.

Gaps

You can increase / decrease the space between windows by pressing alt+g and alt+shift+g, respectively. If you want to change the defaults, edit ~/.config/i3/config (the gaps stuff is near the very end).

Setting the Screen Size

You can put VirtualBox in full screen mode from the menus, or by hitting ctrl-f (using the right control key by default). Normally the resolution will expand to fill the entire screen, leaving no black regions on the sides, top, or bottom. However, in some cases this does not work, and the screen does not fill the entire space. I’ve left a workaround for this already. Here are the steps:

First, you need to figure out what screen resolution is right. To get a list of candidates, you can either lift it from your normal OS, or run this command in the virtual machine, first making sure full screen mode (with the black borders) is active:

$ xrandr -q --current

Look for a mode with a + next to it. This is supposed to be the “preferred” mode for your screen. The current mode will be marked with an asterisk *. For my laptop, 1366x768 is preferred. In what follows, replace that with your choice, of course. Important: you should test out the mode before setting it! Do it like this:

$ modetest 1366x768

Hit ctrl-c if the new resolution looks right (it will be restored automatically in a few seconds otherwise).⁵ Once you have the right mode, do the following to make the changes permanent, again replacing “1366x768” with your choice:

$ ln -s ~/setup/start-i3.sh ~/.config/
$ echo "1366x768" > ~/.config/x11mode

Tiny font on high resolution displays

If you have one of those fancy retina displays, you might find the font in the virtual machine very hard to read. I think the easiest fix is to choose a smaller screen size (see above), and then adjust 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.

Backing Up / Sharing Data

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.

• https://community.linuxmint.com/tutorial/view/100
• http://www.ee.surrey.ac.uk/Teaching/Unix/

Advanced Configuration + Troubleshooting

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

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

3. If you see an error on MacOS about “Installation Failed”, perhaps try this link.

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

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

6. The VM is set to use 1GB of memory, which should be plenty (the desktop and some terminals should take only 60MB). However, if your computer does not have at least 2GB, you will want to reduce this amount, which can be done through the menus “Machine .. settings .. system .. motherboard”. I would try to give it at least 300MB if you want to run firefox, but you can get away with under 100MB and still run all the essential tools.

7. If you don’t like the transparent terminal windows, or if they are misbehaving, you can turn them off via
   sed -i -e 's/\(^picom\)/# \1/' ~/.xinitrc
   and you can turn them back on again by running
   sed -i -e 's/^# \(picom\)/\1/' ~/.xinitrc

8. You might be able to speed things up by enabling 2d acceleration in the virtual machine settings.

9. The username and password of the main account are both csc103 if you ever need them. This is also the root password.

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

11. 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:

1. 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.
2. 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

That’s pretty much it. Enjoy : )

Back to the class homepage