Uhyve

Uhyve is a minimal, special-purpose hypervisor for the Hermit kernel.

Installation

1. Install the Rust toolchain. The Rust Foundation provides installation instructions.
2. 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

macOS

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/hermit-os/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

Assuming that you have installed Uhyve, run the hypervisor to start the unikernel:

uhyve /path/to/the/unikernel/binary

Configuration

Uhyve can be configured using command line arguments and environment variables. This example launches a virtual machine with 4 GiB of memory and 4 cores:

uhyve -m 4GiB -c 4 path/to/unikernel

For more options, the default values, and the corresponding environment variables run:

uhyve --help

Networking

To use tap networking, you need to create a tap device first and connect it to a suitable network interface (needs root). The following script creates a tap device and bridge interface for guest-host networking:

ip link add bridge0 type bridge
ip link set bridge0 up
ip addr add 10.0.5.2/24 brd + dev bridge0
ip tuntap add tap10 mode tap one_queue
ip link set dev tap10 up
ip link set tap10 master bridge0

Configure the IP address and gateway of your Hermit image via HERMIT_IP=10.0.5.3 and HERMIT_GATEWAY=10.0.5.2. Run the image via:

uhyve --net=tap:tap10 path/to/image

The guest can reach the host at 10.0.5.2 and the guest is available on 10.0.5.3

Contributing

If you are interested in contributing to Uhyve, make sure to check out the Uhyve wiki!

Our wiki contains instructions on working with Uhyve's source code, including setting up a suitable development environment, as well as profiling, testing and debugging Uhyve.

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.