[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