BhyveAsVagrantBackend [FreeBSD WIKI]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Support bhyve as a Vagrant VM backend. ======
  * Student: Tong Li (<litong@FreeBSD.com>)
  * Mentors:  Steve Wills (<swills@FreeBSD.org>)  Michael Dexter (<editor@callfortesting.org>)

===== Project description =====
Vagrant is a software tool used to create and configure virtual environment, i.e. virtual machine. It’s like a wrapper around virtualization software to make it easy to use virtual machine in developing. It was tied to virtualbox during its early days. But now it supports many other backends (e.g. hyper-v), which is called provider, and can be easily extended to add more providers through its plugin system (e.g. vagrant-aws). Through this plugin system, we can add bhyve as a provider of Vagrant. So that setting up a bhyve machine can be done only with "vagrant init" and "vagrant up", which will make using bhyve in development much easier.

===== Approach to solving the problem =====

(Details as to how you intend to approach the problem, if applicable. May include ideas as to how to break the problem down into smaller parts, or notes on research you need to do before settling on your final approach to solving the problem)
  * Networking: A method should be used to provide network access and port forwarding features. In the [[https://www.freebsd.org/doc/handbook/virtualization-host-bhyve.html|chapter]] of handbook which introduces how to use bhyve, a bridge and a tap device is created on host to let virtual machines can connect to internet like real machines in the LAN of host. But this may not always work. Actually it can't work on my laptop because the network provide by my college uses static ip address bounded to mac address. So it may be better to use NAT. Referring to vm-bhyve's [[https://github.com/churchers/vm-bhyve/blob/master/lib/vm-switch#L457|implement]], pf and dnsmasq(or maybe dhcpd) is suitable for providing NAT, dhcp and port forwarding on bhyve VMs. vagrant-xhyve also mentioned another [[https://github.com/sirn/vagrant-xhyve/issues/2|method]] to solve port forwarding with socat.
  * Privilege: Not like virtualbox, bhyve needs root privilege to be run, at least for now. And the bridge and tap devices used to provide networking for VMs, pf mentioned above also need super user access. So users needs to have sudo if they have no access to root account. The usage of sudo will be limited as few as possible. Now the creation of networking infrastructure, creating/destroying and booting of VM instances, NAT and port forwarding need to be done under sudo. There are some works aiming at making usage of bhyve with normal user become possible. So the list can be shorter after that part of works are done.

===== Deliverables =====

  * A vagrant plugin (written in ruby) which implements as many commands as possiable.
  * Documents about the plugin.
  * A box for testing the plugin.

===== Status =====

^ Function ^ Status ^
| Box format | Defined |
| Check bhyve support | Working |
| Cloning and booting | Working(needs gcp package to copy image) |
| Network | Working(needs pf and dnsmasq to provider NAT and DHCP) |
| SSH/SSH run | Working(SSH run may needs bash) |
| Graceful shutdown | Working |
| ACPI shutdown | Working |
| Destroying | Working |
| Provision | Working(Basically) |
| Port forwarding | Not working |
| File sharing | Not implemented(Maybe uses NFS at first and waits for bhyve's %%VirtFS%% support) |
| Suspend | Not supported by bhyve yet |
| Resume | Not supported by bhyve yet |

===== Milestones =====

|  Week 1 - 2  | Implement methods needed to run/destroy VMs |
|  Week 3 - 4  | Work on ssh access support |
|  Week 5 - 6  | Finish works about ssh access support. Here is the point we can let people do some basic tests. So that a box for bhyve may also be needed to be created. |
|  MID-TERM  ||
|  Week 7 - 11  | Implement funtionalities which works through the action method as many as possiable. |
|  Week 12  | Arrange documents. |
|  FINAL  ||

===== Test Plan =====

Vagrant has a library, named [[https://github.com/mitchellh/vagrant-spec|vagrant-spec]], providing testing helpers which can be used to write unit and acceptance tests for Vagrant plugins. It includes some acceptance tests which treat Vagrant as a black box. This can be used to test whether the plugin can work with whole Vagrant system correctly. The library also ships with some provider acceptance tests to test its built-in provider virtualbox, these tests can be reused to test basic factionalities of this new plugin. And for the bhyve-specific those might be introduced in, some new test cases should be created to make sure that they work correctly.

===== The Code =====

  * [[https://github.com/jesa7955/vagrant-bhyve|Github]] (Main)
  * [[https://svnweb.freebsd.org/socsvn/soc2016/litong/vagrant-bhyve/|SVN]]

===== Useful links =====

  * [[https://github.com/mitchellh/vagrant-aws|vagrant-aws]] A provider written by the original author of Vagrant, which can be a good example for this project.
  * [[https://github.com/sirn/vagrant-xhyve|vagrant-xhyve]] Provider for xhyve.
  * [[https://www.vagrantup.com/docs/plugins/providers.html|Vagrant Providers]] Vagrant’s documentation about how to create custom providers.
  * [[https://github.com/churchers/vm-bhyve|vm-bhyve]] A management system for bhyve written in shell scripts
  * [[https://blog.docker.com/2016/03/docker-for-mac-windows-beta/|News]] about xhyve: xhyve is used to replace virtualbox as the Linux VM provider of Docker on Max OS X.