Bug 1173409 - Vagrant: Add support for creating a 'scratch' VM

It's sometimes useful to be able to spin up an additional Vagrant
environment without affecting the first. To do this, we create two named
machines, both identical (since they inherit the main Vagrantfile
configuration) - one called default (to match the machine name used up
until now, so we don't force people to recreate their existing VMs when
we land this) and one called scratch.

The former is set to be the primary, so that single-machine commands
(eg `vagrant ssh`) work without having to append the machine name every
time.

The scratch machine has autostart set to false, so that it does not spin
up without explicitly using: `vagrant up scratch`

The name `scratch` is entirely arbitrary, and we can add additional
temporary machine names later, if people wish to have more than two
environments saved simultaneously.

For more information, see:
http://docs.vagrantup.com/v2/multi-machine/

Vagrantfile

@@ -21,6 +21,9 @@ Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
     vb.customize ["modifyvm", :id, "--memory", "1024"]
   end
 
+  config.vm.define "default", primary: true
+  config.vm.define "scratch", autostart: false
+
   config.vm.provision :puppet do |puppet|
     puppet.manifests_path = "puppet/manifests"
     puppet.manifest_file = "vagrant.pp"

docs/common_tasks.rst

@@ -148,3 +148,32 @@ specific datasource, you can do that with that `--datasources` and
 `--data-type` options. Run `./manage.py run_sql --help` for more
 details.
 
+Running multiple Vagrant VMs
+----------------------------
+
+It's sometimes useful to be able to spin up an additional Vagrant
+environment without affecting the first. To do this, append the
+machine name `scratch` onto the standard commands. You will need to
+ensure the default VM is suspended first, since otherwise the exposed
+ports will clash.
+
+  .. code-block:: bash
+
+     $ vagrant suspend
+     $ vagrant up scratch
+       ...
+     $ vagrant status
+       Current machine states:
+       default                   saved (virtualbox)
+       scratch                   running (virtualbox)
+     $ vagrant ssh scratch
+       ...
+     $ vagrant suspend scratch
+     $ vagrant up
+     $ vagrant status
+       Current machine states:
+       default                   running (virtualbox)
+       scratch                   saved (virtualbox)
+
+If you do not provide a machine name for `up` or `ssh`, the command will
+apply to the `default` machine only.