Clawpack Virtual Machine

Using Clawpack requires a variety of other software packages, as summarized in Installation instructions. An alternative to installing the prerequisites is to use the virtual machine described in this section.

Another alternative is to run Clawpack on the Cloud, see Amazon Web Services EC2 Clawpack AMI.

To do so, you need only download and install the VirtualBox software and then download a Virtual Machine (VM) that has been built specifically for Clawpack. VirtualBox will run this machine, which will emulate a version of Ubuntu Linux that already has installed all of the software packages needed.

See the VirtualBox documentation for more about VMs in general.

System requirements

The VM is around 2.5 GB in size, uncompressed, and the virtual disk image may expand to up to 8 GB, depending on how much data you store in the VM. Make sure you have enough free space available before installing. You can set how much RAM is available to the VM when configuring it, but it is recommended that you give it at least 512 MB; since your computer must host your own operating system at the same time, it is recommended that you have at least 1 GB of total RAM.

Setting up the VM in VirtualBox

Once you have downloaded and uncompressed the virtual machine disk image from the download site, you can set it up in VirtualBox, by doing the following:

1. Start VirtualBox
2. Click the New button near the upper-left corner
3. Click Next at the starting page
4. Enter a name for the VM (put in whatever you like); for OS Type, select “Linux”, and for Version, select “Ubuntu”. Click Next.
5. Enter the amount of memory to give the VM, in megabytes. Give it as much as you can spare; 512 MB is the recommended minimum. Click Next.
6. Click Use existing hard disk, then click the folder icon next to the disk list. In the Virtual Media Manager that appears, click Add, then select the virtual machine disk image you downloaded from the class web site. Ignore the message about the recommended size of the boot disk, and leave the box labeled “Boot Hard Disk (Primary Master)” checked. Once you have selected the disk image, click Next.
7. Review the summary VirtualBox gives you, then click Finish. Your new virtual machine should appear on the left side of the VirtualBox window.

Optionally, if you have a reasonably new computer with a multi-core processor and want to be able to run parallel programs across multiple cores, you can tell VirtualBox to allow the VM to use additional cores. To do this, click the VM on the left side of the VirtualBox window, then click Settings. Under System, click the Processor tab, then use the slider to set the number of processors the VM will see. Note that some older multi-core processors do not support the necessary extensions for this, and on these machines you will only be able to run the VM on a single core.

Starting the VM

Once you have configured the VM in VirtualBox, you can start it by double-clicking it in the list of VM’s on your system. The virtual machine will take a little time to start up; as it does, VirtualBox will display a few messages explaining about mouse pointer and keyboard capturing, which you should read.

After the VM has finished booting, it will present you with a login screen; click the button in the center labeled “Clawpack User” to log in as clawuser.

The password is also clawuser.

Shutting down

Click the green running man in the lower left corner and then click “Shut Down” to exit the VM. You can also “Suspend”, which preserves the memory state and is better if a long job is running in the VM that you want to restart later where it left off.

Running programs

You can access the programs on the virtual machine through the main menu (the mouse on an X symbol in the lower-left corner of the screen), or by clicking the quick-launch icons next to the menu button. By default, you will have quick-launch icons for a terminal window and a web browser. After logging in for the first time, you should start the web browser to make sure your network connection is working.

Fixing networking issues

Assuming your computer is connected to the internet, you should also be able to access the internet from the VM. This is necessary if you want to update Clawpack using Git, or to transfer your results from the VM to the host computer (or elsewhere) using sftp.

When a Linux VM is moved to a new computer, it sometimes doesn’t realize that the previous computer’s network adaptor is no longer available. If you find yourself unable to connect to the Internet, open a terminal window and type the following command:

$ sudo rm /etc/udev/rules.d/70-persistent-net.rules

This will remove the incorrect settings; Linux should then autodetect and correctly configure the network interface it boots. To reboot the VM, click the running person icon in the bottom-right of the screen, then click Restart.

Versions of Clawpack

Starting with Version 4.6.0, the VM comes pre-installed with a specific version of Clawpack and has a name such as VirtualClaw-4.6.0. The directory containing Clawpack is then clawpack-4.6.0.

This approach has been chosen since previous versions of Clawpack are then archived along with an operating system on which everything works. This may be advantageous is archiving codes that are used to produce the results in a publication for example, where we recommend that you cite the version of Clawpack used to obtain them.

Of course you are also welcome to install newer versions of Clawpack in a VM for your own use if you choose to. Git is also installed if you want to clone the most recent version from Github, see Development on Github.

Using Clawpack on the VM

See the file ~/clawuser/README.txt for more about using Clawpack on the VM. The file ~/clawuser/INSTALLED.txt has a list of some of the software installed on the VM.

About the VM

The virtual machine is running XUbuntu 9.10, a variant of Ubuntu Linux (http://www.ubuntu.com), which itself is an offshoot of Debian GNU/Linux (http://www.debian.org). XUbuntu is a stripped-down, simplified version of Ubuntu suitable for running on smaller systems (or virtual machines); it runs the xfce4 desktop environment.

Guest Additions

These guest additions are already installed in VirtualClaw, so you should not have to do the following...

Do the following so that the VM will automatically capture and uncapture your mouse depending on whether you click in the VM window or outside it, and to make it easier to resize the VM window to fit your display.

1. Boot the VM, and log in.
2. In the VirtualBox menu bar on your host system, select Devices –> Install Guest Additions... (Note: click on the window for the class VM itself to get this menu, not on the main “Sun VirtualBox” window.)
3. A CD drive should appear on the VM’s desktop, along with a popup window. (If it doesn’t, see the additional instructions below.) Select “Allow Auto-Run” in the popup window. Then enter the password you use to log in.
4. The Guest Additions will begin to install, and a window will appear, displaying the progress of the installation. When the installation is done, the window will tell you to press ‘Enter’ to close it.
5. Right-click the CD drive on the desktop, and select ‘Eject’.
6. Restart the VM.

If step 3 doesn’t work the first time, you might need to:

Alternative Step 3:

1. Reboot the VM.
2. Mount the CD image by right-clicking the CD drive icon, and clicking ‘Mount’.
3. Double click the CD image to open it.
4. Double click ‘autorun.sh’.
5. Enter the VM password to install.

Changing guest resolution/VM window size

This should not be necessary if the Guest Additions are working.

It’s possible that the size of the VM’s window may be too large for your display; resizing it in the normal way will result in not all of the VM desktop being displayed, which may not be the ideal way to work. Alternately, if you are working on a high-resolution display, you may want to increase the size of the VM’s desktop to take advantage of it. In either case, you can change the VM’s display size by going to the main menu in the lower-left corner, pointing to Settings, then clicking Display. Choose a resolution from the drop-down list, then click Apply.

Setting the host key

This should not be necessary if the Guest Additions are working.

When you click on the VM window, it will capture your mouse and future mouse actions will apply to the windows in the VM. To uncapture the mouse you need to hit some control key, called the host key. It should give you a message about this. If it says the host key is Right Control, for example, that means the Control key on the right side of your keyboard (it does not mean to click the right mouse button).

On some systems, the host key that transfers input focus between the VM and the host operating system may be a key that you want to use in the VM for other purposes. To fix this, you can change the host key in VirtualBox. In the main VirtualBox window (not the VM’s window; in fact, the VM doesn’t need to be running to do this), go to the File menu, then click Settings. Under Input, click the box marked “Host Key”, then press the key you want to use.