General Instructions for Running Recomputable Experiments

To run an experiment which we distribute using VirtualBox and Vagrant, no software downloads from
recomputation.org are necessary. However, you will need to install the
tools VirtualBox and Vagrant if you do not have these already. Both tools are free. We provide
brief descriptions and download links for VirtualBox and Vagrant below.
If you cannot install these tools we discuss workarounds below.

Security Warning: There are inevitable security risks in running any executable and/or virtual machine downloaded from the internet. This is particularly true for virtual machines representing experiments in computational science, since they might represent
a historical version of an operating system which may have security flaws fixed in later versions.
You should take appropriate precautions before running any virtual machines from this website.

Using Vagrant in Unix-like Systems

These instructions should work in a Unix-like system with vagrant and VirtualBox installed.
These instructions are limited to Unix-like systems (e.g. Linux, MacOS X). VirtualBox and Vagrant are available for Microsoft Windows
but we have not yet used Vagrant in Windows, therefore have not provided corresponding instructions. (We would be very glad to hear of any
experiences using Vagrant in Windows.)

For the following instructions will assume that you create a new directory to do your work in, e.g.

$ mkdir anydir
$ cd anydir

From now on we assume that commands we give below are in anydir or a subdirectory. We use $ as the Unix command line prompt in the Host machine, % for the prompt in the guest machine, and lines without the prompt represent some form of output.

Instructions for Obtaining and Starting a Vagrant Box

We distribute virtual machines (VMs) as Vagrant Boxes. A box is just Vagrant’s package format for a Virtual Machine, some configuration information, and possibly additional files. To get a box you need its URL, which is given with each experiment listed in this website. We use the CP2013 Experiment 1 experiment as an example. The URL for this Vagrant box is:

http://recomputation.org/cp2013/experiment1/recomputation-QueensPuzzle-b.box

You also need to give your experiment a name of your choice. We use the name “cp2013-experiment1” in this example. Replace the URL placeholder in the following with the actual URL for the box. (If you have downloaded the box to your local computer, you can use the path to the file instead of the URL)

$ vagrant init cp2013-experiment1 URL

This initialises the directory but does not download the Vagrant box. To download the box and start it up type the following command:

$ vagrant up

After the box is downloaded, Vagrant passes the VM to VirtualBox, congfigures it for Vagrant’s needs, and finally starts the VM up.

Disabling Initialisation Scripts

When a VM is booted for the first time, typically the whole experiment is run immediately after booting. To disable this behaviour, instead of the above command, issue the following command:

$ vagrant up --no-provision

Working with a VM

The VM should now be running in VirtualBox in your machine. You could interact with it via VirtualBox, but Vagrant provides an alternative shortcut.

To log in to the VM simply enter:

$ vagrant ssh

You should now be in the machine as user vagrant in ~vagrant (/home/vagrant). This user is normally configured to be a passwordless sudoer in the VM.

Sharing Files Between the Host and the VM

If you want to share work between the VM and the host machine, then do your work in /vagrant. /vagrant is automatically cross mounted with the lcoal directory (anydir above) in which the VM was started. This is achieved by using the shared folders facility of VirtualBox. Note that care may be necessary, since directories actually live in the host OS. Details of the file system may not be consistent between the guest and host machine.

Changing Properties of the VM

If you need more RAM or CPUs (or less) in the VM as distributed in the box, or to change other features, you can use the VBoxManage tool that comes with VirtualBox.

To list available VMs managed by VirtualBox type:

$ VBoxManage list vms
"recomp-cp2013_1371632000" {451e2506-b2b4-4587-8b60-b24e3ea596a2}

To get specific details about the VM with GUID 451e2506-b2b4-4587-8b60-b24e3ea596a2 type:

$ VBoxManage showvminfo 451e2506-b2b4-4587-8b60-b24e3ea596a2
lots of information about the VM

Then to change properties of this VM type:

$ VBoxManage modifyvm 451e2506-b2b4-4587-8b60-b24e3ea596a2 --memory 65536 --cpus 16

See the VBoxManage manual page for more options.

Note that what you change will get stored when you create a new Vagrant package (see below). You can also change these settings in the standard Vagrant configuration file Vagrantfile.

Because the VM is running in VirtualBox, you can also use all other aspects of VirtualBox (e.g. its GUI) to control the box.

Freeing Up Resources Used by an Experiment

The VM continues to run until you shutdown the VM internally, or externally through Vagrant or VirtualBox. It can be halted internally by the normal method of the guest OS. To shutdown externally type:

$ vagrant halt

This shuts down the VM, but leaves VM and its virtual hard disk in VirtualBox. The machine can be restarted by giving the following command in the directory where it was initilised:

$ vagrant up 

The VM will continue remain on your system, either actively or passively, as long as you wish. If you no longer have a need for the VM and wish to save the disk space it uses, perform the following (where cp2013-experiment1 is the local name you gave earlier):

$ vagrant destroy
$ vagrant box remove cp2013-experiment1 virtualbox

Important: The vagrant destroy command does what it says. It destroys the VM so you will lose any changes made within the VM. The exception is that files in anydir will be preserved, e.g. if you have stored results of the experiment there.

Destroying a VM is sensible if you wish to run an experiment, check and/or save its results, and then get rid of the machine. Obviously it is not appropriate if you have made changes to the VM that you wish to save. In that case you should keep the machine and/or repackage it for distribution to others.

Saving a Copy of the VM (i.e. Re-packaging)

If you have made changes to the VM and want to save them - e.g. when your experiment is ready to run, you can do this in the host in directory anydir.

vagrant package --output NewName.box --vagrantfile Vagrantfile

This command packages the current state of the VM into a Vagrant box that can be used by others freely in future, including yourself. The specified Vagrantfile should contain any configuration parameters for the VM when it gets initialised through vagrant up.

An optional step before doing the above (if the guest is Linux), is to zero out the free disk space in the guest. This will allow Vagrant to compress the disk file, but will take some time if the virtual disk is large. Note that this operation is done in the VM (i.e. the guest) and not in the host.

% dd if=/dev/zero of=test.file
% rm test.file

Passwords in the VM

Because of the way the VM is set up you do not normally need to know, but we follow Vagrant conventions to set:

  • Root password: vagrant
  • Login name: vagrant
  • Login password: vagrant

Also vagrant user is a passwordless sudoer in the VM.

Vagrant Documentation

For further details on Vagrant see http://docs.vagrantup.com/v2/.

Downloads

VirtualBox

VirtualBox is a mainly free and open source product from Oracle,
although some parts of it are closed. It describes itself
as a “a general-purpose full virtualizer for x86 hardware, targeted at server, desktop and embedded use”
https://www.virtualbox.org/wiki/VirtualBox

The bulk of VirtualBox is open source under GPL. However there are extensions of it which are closed and not free, although can be used for personal use, education and evaluation. For details of these licence terms see the VirtualBox PUEL. The most important thing we use from the extensions are the “VirtualBox Guest Additions”, as these are required for Vagrant to work. We distribute the guest additions in the vagrant boxes we distribute, under the right granted to us by the VirtualBox PUEL.

You can download VirtualBox for many host operating systems and it can also often be installed through Linux package managers.

Vagrant

Vagrant is a tool which makes interaction with VirtualBox or other virtualisation products much easier. It is entirely free and open source for use with VirtualBox.

Vagrant can be downloaded from vagrantup.com. It can be installed from package managers in some versions of Linux, but ensure that you have a recent version.

Vagrant was started by Mitchell Hashimoto and commercialised by HashiCorp.
It remains open source with a github page.

Workarounds

If you have VirtualBox but not Vagrant, you should have little problem running our experiments. A Vagrant “box” is actually just a tar file containing some configuration information and an exported virtual machine from VirtualBox. Therefore you could do:

$ mkdir anydir
$ cd anydir
$ wget URL          ## (if not downloaded already) 
$ tar xf FILENAME.box

If using the VM without Vagrant you will need to know the default passwords given earlier. You should now have the files in anydir to give to VirtualBox.

The only difficulty you might find is how to run the experiment if it is run automatically by vagrant up. If you are having difficulty then you should look at the experiment documentation on this site, any README files in the machine, or the Vagrantfile included with the box.

If you have another virtualisation product (e.g. VMWare), it might be possible to import the VM using that product. We have not tested this scenario but programs are often able to import each others’ machines (Note that it is very unwise to install more than one virtualisation product unless you know exactly
what you are doing, as their low level functions can interfere catastrophically with each other).

If you have no virtualisation product available, then we normally try to release other files which can beused to run the experiment. E.g. we might release a tarred and/or zipped copy of the experimental directory. You might find this is able to run in your system, but also there might be problems doing so because of version inconsistencies of software. These are precisely the reason for providing virtual machines.