Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,15 +139,15 @@ At the moment, `urunc` is available on GNU/Linux for x86\_64 and arm64 architect
In addition, the following table provides an overview of the currently
supported VM/Sandbox monitors and unikernels:

| Unikernel | VM/Sandbox Monitor | Arch | Storage |
| --------- | -------------------------- | ----------- | --------------------------------------- |
| Rumprun | Solo5-hvt, Solo5-spt | x86,aarch64 | Block/Devmapper |
| Unikraft | QEMU, Firecracker, Hyperlight | x86 | Initrd, 9pfs |
| MirageOS | QEMU, Solo5-hvt, Solo5-spt | x86,aarch64 | Block/Devmapper |
| Mewz | QEMU | x86 | In-memory |
| Linux | QEMU, Firecracker, Cloud-Hypervisor | x86,aarch64 | Initrd, Block/Devmapper, 9pfs, Virtiofs |
| Hermit | QEMU | x86 | Initrd |
| FreeBSD | Firecracker, QEMU | x86 | Block/Devmapper/9pfs (Qemu) |
| Unikernel | VM/Sandbox Monitor | Arch | Storage |
| --------- | ---------------------------------------- | ----------- | --------------------------------------- |
| Rumprun | Solo5-hvt, Solo5-spt | x86,aarch64 | Block/Devmapper |
| Unikraft | QEMU, Firecracker, Hyperlight | x86 | Initrd, 9pfs |
| MirageOS | QEMU, Solo5-hvt, Solo5-spt | x86,aarch64 | Block/Devmapper |
| Mewz | QEMU | x86 | In-memory |
| Linux | QEMU, Firecracker, Cloud-Hypervisor, hvi | x86,aarch64 | Initrd, Block/Devmapper, 9pfs, Virtiofs |
Comment thread
Nachiket-Roy marked this conversation as resolved.
Resolved
| Hermit | QEMU | x86 | Initrd |
| FreeBSD | Firecracker, QEMU | x86 | Block/Devmapper/9pfs (Qemu) |

We plan to add support for more unikernel frameworks and other platforms too.
Feel free to [contact](#Contact) us for a specific unikernel framework or similar
Expand Down
6 changes: 6 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,6 +155,7 @@ values.
- [Solo5-hvt](./hypervisor-support#solo5-hvt) - `hvt` - Solo5 hvt (KVM-based tender)
- [Solo5-spt](./hypervisor-support#solo5-spt) - `spt` - Solo5 spt (Seccomp-based tender)
- [Hyperlight](./hypervisor-support#hyperlight) - `hyperlight-unikraft`
- [hvi](./hypervisor-support#hvi) - `hvi`

#### Monitor Options

Expand Down Expand Up @@ -336,6 +337,11 @@ default_vcpus = 1
# default_memory_mb is not applied: without a limit, hluk sizes the guest itself
default_vcpus = 1
# path is not set by default - urunc will search in PATH

[monitors.hvi]
default_memory_mb = 256
default_vcpus = 1
# path is not set by default - urunc will search in PATH
```

## Notes
Expand Down
2 changes: 2 additions & 0 deletions docs/design/seccomp.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@ supported VMM. In particular, in the case of:
of seccomp by itself, as of Solo5 v0.11.0.
- Solo5-spt, 'urunc' can not do anything since solo5-spt makes use of seccomp by
itself.
- hvi, 'urunc' relies on hvi's internal seccomp sandbox filters by default,
and disables them with `--no-sandbox` when container seccomp is unconfined.

## Caveats of using seccomp in 'urunc'

Expand Down
46 changes: 44 additions & 2 deletions docs/hypervisor-support.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,12 @@ somewhere in the `$PATH`.
VMMs use hardware-assisted virtualization technologies in order to create a
Virtual Machine (VM) where a guest OS will execute. It is one of the most
widely used technologies for providing strong isolation in multi-tenant
environments. For the time being `urunc` supports 4 types of such VMMs: 1)
environments. For the time being `urunc` supports 6 types of such VMMs: 1)
[Qemu](https://www.qemu.org/), 2)
[Firecracker](https://firecracker-microvm.github.io/), 3)
[Cloud Hypervisor](https://www.cloudhypervisor.org/) and 4) [Solo5-hvt](https://github.com/Solo5/solo5).
[Cloud Hypervisor](https://www.cloudhypervisor.org/), 4) [Solo5-hvt](https://github.com/Solo5/solo5), 5)
[Hyperlight](https://github.com/hyperlight-dev/hyperlight) and 6)
[hvi](https://github.com/brig-sh/hvi-vmm).

### Qemu

Expand Down Expand Up @@ -385,6 +387,46 @@ An example unikernel:
sudo nerdctl run --rm -ti --runtime io.containerd.urunc.v2 docker.io/urunc/hello-hyperlight-unikraft:v[[ versions["hyperlight-unikraft"] ]]
```

### hvi

[hvi](https://github.com/brig-sh/hvi-vmm) is a minimal, lightweight KVM-based
microVMM designed for running Linux guests with minimal footprint and strong
isolation. Distributed as a single Rust executable for x86-64 and aarch64, `hvi`
provides a simple device model where all devices reside on `virtio-mmio` and the
VMM enforces its own internal seccomp sandbox filters.

#### Installing hvi

`hvi` can be built and installed directly from source using the Rust toolchain:

```bash
git clone https://github.com/brig-sh/hvi-vmm.git
cd hvi-vmm
cargo build --release
sudo install -m0755 target/release/hvi /usr/local/bin/hvi
```

`urunc` expects the `hvi` binary to be available in `$PATH` or configured via
`monitors.hvi.path`.

#### hvi and `urunc`

`urunc` integrates with `hvi` to boot uncompressed ELF Linux kernel binaries
(`vmlinux` on x86-64, `Image` on aarch64) using `virtio-mmio` devices for block
storage and networking, as well as vhost-user virtiofs for shared filesystem support.
By default, `urunc` runs `hvi` with its internal seccomp sandbox enabled, or disables
it with `--no-sandbox` when container seccomp is unconfined.

Supported guests with `urunc`:

- [Linux](../unikernel-support#linux)

An example guest:

```bash
sudo nerdctl run --rm -ti --runtime io.containerd.urunc.v2 harbor.nbfc.io/nubificus/urunc/busybox-hvi-linux-raw:latest
```

## Software-based isolation monitors

Except for the traditional VM-based isolation solutions, there are other
Expand Down
2 changes: 1 addition & 1 deletion docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Sandbox monitors, along with the unikernels that can run on top of them.
| [Unikraft](./unikernel-support#unikraft)| [Qemu](./hypervisor-support#qemu), [Firecracker](./hypervisor-support#aws-firecracker), [Hyperlight](./hypervisor-support#hyperlight) | x86 | Initrd, 9pfs |
| [MirageOS](./unikernel-support#mirage)| [Qemu](./hypervisor-support#qemu), [Solo5-hvt](./hypervisor-support#solo5-hvt), [Solo5-spt](./hypervisor-support#solo5-spt) | x86, aarch64 | Block/Devmapper |
| [Mewz](./unikernel-support#mewz)| [Qemu](./hypervisor-support#qemu) | x86 | In-memory |
| [Linux](./unikernel-support#linux)| [Qemu](./hypervisor-support#qemu), [Firecracker](./hypervisor-support#aws-firecracker), [Cloud-Hypervisor](./hypervisor-support#cloud-hypervisor) | x86, aarch64 | Initrd, Block/Devmapper, 9pfs, Virtiofs |
| [Linux](./unikernel-support#linux)| [Qemu](./hypervisor-support#qemu), [Firecracker](./hypervisor-support#aws-firecracker), [Cloud-Hypervisor](./hypervisor-support#cloud-hypervisor), [hvi](./hypervisor-support#hvi) | x86, aarch64 | Initrd, Block/Devmapper, 9pfs, Virtiofs |
| [Hermit](./unikernel-support#hermit)| [Qemu](./hypervisor-support#qemu) | x86 | Initrd |
| [FreeBSD](./unikernel-support#freebsd)| [Firecracker](./hypervisor-support#aws-firecracker), [QEMU](./hypervisor-support#qemu) | x86 | Block/Devmapper/9pfs (Qemu) |

Expand Down
13 changes: 13 additions & 0 deletions docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ with virtiofsd. Specifically:
- [firecracker](https://github.com/firecracker-microvm/firecracker)
- [Cloud-Hypervisor](https://github.com/cloud-hypervisor/cloud-hypervisor)
- [Hyperlight-unikraft](https://github.com/hyperlight-dev/hyperlight-unikraft)
- [hvi](https://github.com/brig-sh/hvi-vmm)
- [virtiofsd](https://virtio-fs.gitlab.io/)

**3. Installation and configuration of `urunc`**
Expand Down Expand Up @@ -492,6 +493,18 @@ Alternatively, `hluk` can be installed from
[crates.io](https://crates.io/crates/hyperlight-unikraft) with
`cargo install hyperlight-unikraft`.

### hvi

[hvi](https://github.com/brig-sh/hvi-vmm) is built from source using the Rust
toolchain:

```bash
git clone https://github.com/brig-sh/hvi-vmm.git
cd hvi-vmm
cargo build --release
sudo install -m0755 target/release/hvi /usr/local/bin/hvi
```

### Virtiofsd

As an alternative to 9pfs, `urunc` can configure Qemu to use
Expand Down
2 changes: 1 addition & 1 deletion docs/package/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ required annotations are the following:
supported values: a) unikraft, b) rumprun, c) mirage.
- `com.urunc.unikernel.hypervisor`: The VMM or sandbox monitor to run the
unikernel. Currently supported values: a) `qemu`, b) `firecracker`, c)
`cloud-hypervisor`, d) `spt`, e) `hvt`, f) `hyperlight-unikraft`.
`cloud-hypervisor`, d) `spt`, e) `hvt`, f) `hyperlight-unikraft`, g) `hvi`.
- `com.urunc.unikernel.binary`: The path to the unikernel binary inside the
container's rootfs. Optional for `hyperlight-unikraft`, whose `hluk` boots
an embedded kernel when the image ships none.
Expand Down
13 changes: 11 additions & 2 deletions docs/unikernel-support.md
Original file line number Diff line number Diff line change
Expand Up @@ -314,8 +314,9 @@ emulated devices etc.).
Focusing on the single-application notion of using the
[Linux](https://github.com/torvalds/linux) kernel, `urunc` provides support for
[Qemu](https://qemu.org),
[Firecracker](https://github.com/firecracker-microvm/firecracker) and
[Cloud-Hypervisor](https://www.cloudhypervisor.org/). For network,
[Firecracker](https://github.com/firecracker-microvm/firecracker),
[Cloud-Hypervisor](https://www.cloudhypervisor.org/) and
[hvi](https://github.com/brig-sh/hvi-vmm). For network,
`urunc` will make use of virtio-net either through PCI or MMIO, depending on
the monitor. In the case of storage, `urunc` can use initrd, virtio-block, 9pfs
or Virtiofs. In particular, `urunc` takes advantage of the extensive filesystem
Expand Down Expand Up @@ -353,6 +354,14 @@ An example of a Nginx alpine image on top of
sudo nerdctl run --rm -ti --runtime io.containerd.urunc.v2 harbor.nbfc.io/nubificus/urunc/nginx-cloud-hypervisor-linux-raw:latest
```

An example of a Busybox alpine image on top of
[hvi](https://github.com/brig-sh/hvi-vmm) and
[Linux](https://github.com/torvalds/linux) with 'urunc':

```bash
sudo nerdctl run --rm -ti --runtime io.containerd.urunc.v2 harbor.nbfc.io/nubificus/urunc/busybox-hvi-linux-raw:latest
```

## Hermit

[Hermit](https://hermit-os.org/) is a unikernel designed for
Expand Down
1 change: 1 addition & 0 deletions pkg/unikontainers/annotations.go
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,7 @@ var supportedGuestMonitorPairs = map[guestMonitorPair]bool{
{hypervisors.FirecrackerVmm, unikernels.FreeBSDUnikernel}: true,
{hypervisors.CloudHypervisorVmm, unikernels.LinuxUnikernel}: true,
{hypervisors.HyperlightVmm, unikernels.UnikraftUnikernel}: true,
{hypervisors.HviVmm, unikernels.LinuxUnikernel}: true,
}

// A UnikernelConfig struct holds the info provided by bima image on how to execute our unikernel
Expand Down
1 change: 1 addition & 0 deletions pkg/unikontainers/annotations_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -490,6 +490,7 @@ func TestValidateValuesGuestMonitorPairs(t *testing.T) {
{"rumprun on qemu", string(hypervisors.QemuVmm), unikernels.RumprunUnikernel},
{"mewz on hvt", string(hypervisors.HvtVmm), unikernels.MewzUnikernel},
{"hedge is not implemented", string(hypervisors.HedgeVmm), unikernels.UnikraftUnikernel},
{"unikraft on hvi", string(hypervisors.HviVmm), unikernels.UnikraftUnikernel},
}

for _, tc := range rejected {
Expand Down
164 changes: 164 additions & 0 deletions pkg/unikontainers/hypervisors/hvi.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,164 @@
// Copyright (c) 2023-2026, Nubificus LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package hypervisors

import (
"errors"
"strconv"

"github.com/urunc-dev/urunc/pkg/unikontainers/types"
"golang.org/x/sys/unix"
)

const (
HviVmm VmmType = "hvi"
HviBinary string = "hvi"
)

type HVI struct {
binaryPath string
binary string
}

func (h *HVI) Signal(pid int, signal unix.Signal) error {
return signalProcess(pid, signal)
}

func (h *HVI) Stop(pid int) error {
return killProcess(pid)
}

func (h *HVI) Ok() error {
return nil
}

// UsesKVM returns true as hvi is a KVM-based VMM on Linux
func (h *HVI) UsesKVM() bool {
return true
}

// UsesTUNTAP reports that the guest gets its network through a tap device.
func (h *HVI) UsesTUNTAP() bool {
return true
}

// SupportsControlSocket reports that hvi exposes no control/API socket.
func (h *HVI) SupportsControlSocket() bool {
return false
}

// SupportsSharedfs returns true as hvi supports vhost-user virtiofs on Linux
func (h *HVI) SupportsSharedfs(fsType string) bool {
switch fsType {
case "virtio":
return true
default:
return false
}
}

func (h *HVI) Path() string {
return h.binaryPath
}

// BuildExecCmd builds and validates the hvi command arguments without executing.
func (h *HVI) BuildExecCmd(args types.ExecArgs, ukernel types.Unikernel) ([]string, error) {
if args.UnikernelPath == "" {
return nil, errors.New("kernel path is required for hvi")
}

// hvi requires the "boot" subcommand
exArgs := []string{h.binaryPath, "boot", "--kernel", args.UnikernelPath}

// Memory configuration in MiB
if args.MemSizeB > 0 {
memMiB := bytesToMiB(args.MemSizeB)
if memMiB == 0 {
memMiB = DefaultMemory
}
exArgs = append(exArgs, "--mem-mib", strconv.FormatUint(memMiB, 10))
}

// vCPU configuration
if args.VCPUs > 0 {
exArgs = append(exArgs, "--cpus", strconv.FormatUint(uint64(args.VCPUs), 10))
}

// Network configuration (separate --net-tap and --net-mac flags)
if args.Net.TapDev != "" {
exArgs = append(exArgs, "--net-tap", args.Net.TapDev)
if args.Net.MAC != "" {
exArgs = append(exArgs, "--net-mac", args.Net.MAC)
}
}

// Block device configuration: --disk path=<path>[,serial=<id>] (max 4 block devices)
blockArgs := ukernel.MonitorBlockCli()
if len(blockArgs) > 4 {
return nil, errors.New("hvi supports at most 4 block devices")
}
for _, blockArg := range blockArgs {
if len(blockArg.ExactArgs) > 0 {
exArgs = append(exArgs, blockArg.ExactArgs...)
} else if blockArg.Path != "" {
diskArg := "path=" + blockArg.Path
if blockArg.ID != "" {
diskArg += ",serial=" + blockArg.ID
}
exArgs = append(exArgs, "--disk", diskArg)
}
}

// Initramfs configuration (hvi supports a single --initramfs flag)
extraMonArgs := ukernel.MonitorCli()
initrdPath := args.InitrdPath
if initrdPath == "" {
initrdPath = extraMonArgs.ExtraInitrd
}
if initrdPath != "" {
exArgs = append(exArgs, "--initramfs", initrdPath)
}

// Shared filesystem configuration (virtiofs over vhost-user)
switch args.Sharedfs.Type {
case "virtiofs":
exArgs = append(exArgs, "--fs", "tag=fs0,socket=/tmp/vhostqemu")
default:
// No shared filesystem
}

// Seccomp sandbox configuration (--no-sandbox when seccomp is disabled)
if !args.Seccomp {
exArgs = append(exArgs, "--no-sandbox")
}

if len(extraMonArgs.OtherArgs) > 0 {
exArgs = append(exArgs, extraMonArgs.OtherArgs...)
}

// Command line arguments for the guest kernel
if args.Command != "" {
exArgs = append(exArgs, "--cmdline", args.Command)
}

vmmLog.WithField("hvi command", exArgs).Debug("Ready to execve hvi")

return exArgs, nil
}

// PreExec performs pre-execution setup. hvi has no special pre-exec requirements.
func (h *HVI) PreExec(_ types.ExecArgs) error {
return nil
}
Loading