Code Layout - churchers/vm-bhyve GitHub Wiki

An overview of the files that make up vm-bhyve and their purpose.

./vm

This is the main command run by users. This contains very little logic and merely performs a few checks to make sure vm-bhyve is enabled, the libraries & $vm_dir exist, and that the operating system and current user are ok. If running on ZFS, we replace $vm_dir with the mount point for the specified dataset. Then __parse_cmd is called to find out what function the user wants to perform.

All functionality is stored in the library files, normally stored in /usr/local/lib/vm-bhyve/. We also look in ./lib/ for library files, allowing you to run vm directly from the current directory, which is useful for development.

./lib/vm-cmd

This contains a few case statements that work out the command requested by the user, and run the appropriate function. This file also contains the function that parses global vm options.

./lib/vm-config

The functions that parse configuration files and return config variables. We have a simple config loader, that reads a config file and stores it in a global variable. The __config_get function looks through this global variable for the requested setting and returns it if found. Due to the small amount of code in this file, it may eventually be moved to vm-common.

./lib/vm-core

All the functions that handle basic commands such as start|stop|install|iso|console|etc. The majority of commands (other than switch or zfs specific commands) are handled by functions in this file. This file used to also contain the code to run bhyve, before it became too large and was moved into vm-run.

./lib/vm-guest

This file contains code required to run the bootloader (bhyveload or grub-bhyve) for guests that require it. We used to have a function for each operating system, however all guests are now handled by the generic __guest_load function. As this file now only contains 2 functions, it may eventually be folded back into vm-run.

./lib/vm-info

vm-bhyve has two "info" commands (vm info [guest] & vm switch info [switch]) that output a wealth of information about guests and switches. This requires a fair amount of code, thus it was decided to implement these functions in their own source file.

./lib/vm-rctl

Code to assign rctl limits to the bhyve process. This function is actually called before bhyve starts running, and then waits until bhyve starts. This is because once bhyve is started, our code blocks until it exits.

./lib/vm-run

This is the main logic for starting bhyve. All code to generate the bhyve device string, create console ports, assign networking interfaces, is in this file. We build up the bhyve command in various variables (_devices, _comstring, _opts, _iso_dev), and all guests are handled by one call to bhyve.

./lib/vm-switch

All code to handle vm switch ... commands lives in this file. This also contains switch library functions such as __vm_switch_id that take a switch name, and return the associated bridge interface name.

./lib/vm-sysrc

Functions that handle updating configuration files using sysrc. Sometimes we need to append a value into an existing configuration setting, or remove it, which is handled by functions in this file. As with vm-config this is short enough that we may fold this into vm-common eventually.

./lib/vm-util

This contains various common utility functions. Commonly used functions such as util::err and util::log are stored here.

./lib/vm-zfs

Functions to handle all ZFS functions. Code to handle snapshot/clone/rollback and all the vm image commands is in this file.

We also have a __zfs_init function that handles setting vm-bhyve up correctly when running on ZFS. In all cases $vm_dir should be the file system path to the vm-bhyve data. For ZFS however, we ask the user to provide "zfs:pool/vm" instead of the file system path. The __zfs_init function makes sure ZFS is running, then gets the mount point for the specified dataset. If successful, the mount point is stored in $vm_dir and the dataset is put into the global $VM_ZFS_DATASET variable. This means the bulk of the vm-bhyve code can use $vm_dir as normal, and any functions that need to access the ZFS dataset directly can use $VM_ZFS_DATASET.