Awesome
<img width="200" align="right" src="img/uhyve.svg" />Uhyve - A minimal hypervisor for Hermit
Introduction
Uhyve is a small hypervisor specialized for the Hermit kernel.
[!WARNING] For the time being, Uhyve provides the unikernel full host file system access with the permissions of the user running Uhyve. Thus, it should not be used for applications which require isolation from the host system.
Installation
- Install the Rust toolchain. The Rust Foundation provides installation instructions.
- Install Uhyve:
cargo install --locked uhyve
Requirements
Linux
To check if your system supports virtualization, you can use the following command:
if egrep -c '(vmx|svm)' /proc/cpuinfo > /dev/null; then echo "Virtualization support found"; fi
Uhyve on Linux depends on the virtualization solution KVM (Kernel-based Virtual Machine). If the following command gives you some output, you are ready to go!
lsmod | grep kvm
[!NOTE] If the above steps don't work, make sure that you have enabled virtualization in your UEFI/BIOS settings.
macOS
[!WARNING] Currently, Uhyve is mainly developed for Linux. The macOS version has not been tested extensively and does not support all features of the Linux version.
You can install Apple's Xcode Command Line Tools using the following command:
xcode-select --install
Additionally, the included hypervisor bases on the Hypervisor Framework depending on OS X Yosemite (10.10) or newer.
To verify if your processor is able to support this framework, run the following in your Terminal:
sysctl kern.hv_support
The output kern.hv_support: 1
indicates virtualization support.
Starting with Big Sur, all processes using the Hypervisor API must have the com.apple.security.hypervisor entitlement and therefore must be signed.
Building from source
To build from source, simply checkout the code and use cargo build
:
git clone https://github.com/hermitcore/uhyve.git
cd uhyve
cargo build --release
macOS Big Sur: Signing Uhyve
uhyve
can be self-signed using the following command:
codesign -s - --entitlements app.entitlements --force path_to_uhyve/uhyve
The file app.entitlements
must have following content:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>com.apple.security.hypervisor</key>
<true/>
</dict>
</plist>
For further information, please consult Apple's Documentation.
Usage
Running Hermit apps within Uhyve
Assuming that you have installed Uhyve, run the hypervisor to start the unikernel:
uhyve /path/to/the/unikernel/binary
[!NOTE] This repository ships a few binaries that can be used for testing.
If you want to compile Hermit binaries yourself (or create your own), take a look at the following repositories:
Configuration
Uhyve can be configured using environment variables. The following variables are supported:
HERMIT_CPUS
: specifies the number of cores the virtual machine may use.HERMIT_MEM
: defines the memory size of the virtual machine. The suffixes M and G can be used to specify a value in megabytes or gigabytes, respectively.- setting
HERMIT_VERBOSE
to1
makes the hypervisor print kernel log messages to the terminal. HERMIT_GDB_PORT=port
activate a gdb server for the application running inside Uhyve. See below
By default, the loader initializes a system with one core and 512 MiB RAM.
Example: the following command starts the demo application in a virtual machine, which has 4 cores and 8GiB memory:
HERMIT_CPUS=4 HERMIT_MEM=8G uhyve /path/to/the/unikernel/binary
Known issues
- Uhyve isn't able to pass more than 128 environment variables to the unikernel.
Licensing
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Contributing
Testing Hermit apps using cargo run
As mentioned above, the Uhyve repository ships some binaries that can be used for testing purposes.
cargo run -- -v data/x86_64/rusty_demo
cargo run -- -v data/x86_64/hello_world
cargo run -- -v data/x86_64/hello_c
Debugging Hermit apps
Basic support of (single-core) applications is already integrated into Uhyve.
By specifying variable HERMIT_GDB_PORT=port
, Uhyve is working as gdbserver and is waiting on port port
for a connection to a gdb.
For instance, with the following command Uhyve is waiting on port 6677
for a connection.
HERMIT_GDB_PORT=6677 uhyve /path_to_the_unikernel/hello_world
In principle, every gdb-capable IDE should be able to debug Hermit applications. (Eclipse, VSCode, ...)
Visual Studio Code / VSCodium
The repository hermit-rs provides example configuration files to debug a Hermit application with Visual Studio Code, VSCodium or derivatives of Eclipse Theia.