[vbox-dev] linktool: host to guest interface link mapper

[Petar Bogdanovic]

Hi,

as it is right now, bridged guest interfaces won't adapt any link
changes of their bridged counterparts.  Manually setting or unsetting
the "cable connected" checkbox is an option but not a very practical one
if you need to roam often and would like your VM to pick up the change
automatically.

linktool is a small set of simple utilities that can make that process
transparent.  It's currently OSX only since it relies on scutil(8) but
that could easily be adjusted in future.

In order to use linktool, copy

	http://smokva.net/src/linktool.sh

somewhere, make it executable and add the following line to your
rc.local (or create an equivalent launchd.plist for root):

	# linktool, absolute paths only
	/path/to/linktool setup /path/to/VirtualBox.app

and that should be it.  All VMs that contain bridged interfaces should
automagically adapt any link changes on their next start.


Details for non-TLDR readers:

linktool consists of several helpers that do a smaller part of the whole
job mentioned in the introduction:

	$ linktool
	usage:
		linktool watch host-if [host-if..]
		linktool map guest host-if:guest-if[:guest-if..] [host-if:guest-if[:guest-if..]..]
		linktool mapper guest
		linktool wrapper --startvm guest
		linktool seesaw master-host-if slave-host-if
		linktool setup vbox-dir vbox-cmd

		guest      : name or UUID of any VM
		host-if    : host interface (see ifconfig)
		guest-if   : guest interface (integer, 1-8)
		vbox-dir   : path to VirtualBox.app directory
		vbox-cmd   : name of VirtualBox command

linkwatch uses scutil(8) and watches host interfaces:

	$ linktool watch en0 en1
	en0:on		# initial output
	en1:off		# initial output
	en1:on		# link status of en1 changed

linkmap maps host interfaces to guest interfaces:

	$ linktool map "My Virtual Machine" en0:1:2
	Mapping link status (on): localhost/en0 -> My Virtual Machine/nic1
	Mapping link status (on): localhost/en0 -> My Virtual Machine/nic2

linkmapper maps all bridged interfaces of a guest.  Its output looks
similar to the output above.

linkwrapper is a wrapper around linkmapper and tries to act like
VirtualBoxVM i.e. it understands the --startvm flag.

linksetup replaces VirtualBoxVM with a plain-text hook that starts
linkwrapper first followed by VirtualBoxVM-$(uname -m).  It needs to
run on every boot since VirtualBoxStartup.sh will otherwise persist
(and remove/relink VirtualBoxVM).

linkseesaw doesn't have much to do with linktool or VirtualBox.  It
reuses linkwatch, downs the slave interface if the master interface is
up and vice versa.


Issues:

	* VBoxHeadless is not supported (shouldn't be hard to add)

	* Switching link status doesn't work well with all virtual
	  network devices.  e1000 is the most reliable choice,  while
	  virtio-net mostly works although it sometimes gets stuck
	  in a state that is only recoverable by unloading and loading
	  the module (on Linux guests).  In that state, showvminfo
	  reports link status A while ethtool claims link status B.

	* Complicated bridging setups (two guest interfaces bridged with
	  one host interface for example) can be unreliable too.  If you
	  can't get any packets through but tcpdump happily reports arp
	  traffic.. simplify your setup.


I've been using linktool for all my VMs since about a month and I pretty
much forgot about it.

Comments & questions are welcome.

Thanks,

		Petar Bogdanovic