Vagrant environment

This page describes the project's Vagrant environment, which is used during development to virtualize the machines on the vehicle.

Virtualization primer

If you are unfamiliar with virtualization and what it offers, the following resources might be a good place to start before reading ahead:

• Why is virtualization useful?
• Why Vagrant?

Vagrantfile

The Vagrantfile is the single file that contains all of the details of the Vagrant setup for the project. This file defines each of the available Virtual Machines (VMs), their names, what operating system (called "box") it should use, what steps should be performed when starting it (called provisioning, e.g. installing software dependencies), and what resources the host machine should offer to it.

The project includes a Vagrant multi-machine environment to model the topology of the ROV. As such, the Vagrantfile defines five virtual machines (VMs):

• rasprime
• topside
• captain
• picamera1
• picamera2

Working with Vagrant

Before working with Vagrant, make sure you have the following installed:

• VirtualBox
• Vagrant

Note that installing Vagrant 1.8.x or newer will install VirtualBox for you if you do not have VirtualBox installed.

You need to have both installed before running any of the commands below will work.

To familiarise yourself with Vagrant, have a read through the Getting Started section from the Vagrant website. Vagrant has a lot of features, but only a subset of them are used in this project.

You can see the list of VMs defined and their current status by running:

vagrant status

To create and start the a particular VM, you can run (substituting $name for the name of the VM you want, chosen from the output of the command above):

vagrant up $name

To SSH into a VM, you can run:

vagrant ssh $name

When you want to power off all machines, you can run:

vagrant halt

Machines

The Vagrant configuration defines a machine to play the role of each physical machine on the ROV as well as an extra machine, dubbed captain, used to aid development. An important note

topside

Important: do not create the topside VM when the physical topside computer is attached to the network as both are configured to have a static IP address (192.168.88.2). Spooky ghosts occur when more machines have the same IP address on a particular network.

The topside VM mimics the topside computer.

captain

rasprime

picamera{1,2}

Tips & tricks

A few notes:

Networking

On the ROV, the Raspberry Pis will be connected to a managed switch to the topside to form a local network. This same networking setup can be modelled using Vagrant. Running vagrant up will statically assign the topside VM an IP address of 192.168.88.2 (where the IP address of the switch is by convention .1) and install a DHCP server. As such, when running vagrant up $name, where $name is the name of another machine in the setup, the topside VM will assign it an IP address.

Particularly useful is the ability to bridge an adapter on the host machine to the Vagrant environment, allowing the Vagrant defined VMs to talk to physical hardware attached via the switch to the host machine. To do this, you will need to add the full name of the host machine's ethernet adapter to the NETWORK_INTERFACES array at the top of the Vagrantfile. You can get the full name of the interface by running:

VBoxManage list bridgedifs

If you are using Windows®, you will need to use the full path to the executable in Command Prompt. From How to run VBoxManage.exe:

"C:\Program Files\Oracle\VirtualBox\VBoxManage.exe" list bridgedifs

See also: Vagrant Networking

SSH and Windows®

Windows® and SSH don't really get along. So, unfortunately, vagrant ssh doesn't "just work". The good news is that there are a lot of ways to get it to work. The easiest method is likely to use PuTTY.

Squid proxy

A Squid proxy server is installed on the captain VM. This allows you to use the captain VM as a proxy for internet traffic from any machine on the same local network (i.e. 10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16). You can use this proxy by starting the topside VM:

vagrant up topside

And setting your http_proxy and https_proxy environment variables to http://192.168.88.3/:

export http_proxy=http://192.168.88.3:3128/
export https_proxy=http://192.168.88.3:3128/

Important: when running commands as root via sudo, you will need to pass the -E flag to keep your environment variables (see sudo(8) for details).

Summary of the super-duper-important bits

• Do not run vagrant up topside if the physical topside computer is attached to the network
• When running a command via sudo, use the -E flag to keep environment variables (e.g. proxy setting)