From 37e5e69fbaf142cfade6a9a6d4fb450b32105d4f Mon Sep 17 00:00:00 2001 From: Nachiket Roy Date: Sat, 14 Nov 2026 17:44:25 +0530 Subject: [PATCH 1/3] feat(monitor): add hvi monitor implementation Introduce the HVI monitor implementation for interacting with the hvi microVMM. Support building the execution command line for booting Linux guests, including kernel, initramfs, memory, vCPUs, TAP networking, block devices (max 4), virtiofs over vhost-user, and seccomp sandboxing. Register HviVmm in the VMM factory map and enable the (hvi, linux) guest-monitor pair in annotations validation and linux unikernel. Signed-off-by: Nachiket Roy --- pkg/unikontainers/annotations.go | 1 + pkg/unikontainers/annotations_test.go | 1 + pkg/unikontainers/hypervisors/hvi.go | 164 +++++++++++ pkg/unikontainers/hypervisors/hvi_test.go | 259 ++++++++++++++++++ .../hypervisors/hyperlight_test.go | 2 +- pkg/unikontainers/hypervisors/utils_test.go | 1 + pkg/unikontainers/hypervisors/vmm.go | 6 + pkg/unikontainers/hypervisors/vmm_test.go | 9 + pkg/unikontainers/unikernels/linux.go | 6 +- 9 files changed, 445 insertions(+), 4 deletions(-) create mode 100644 pkg/unikontainers/hypervisors/hvi.go create mode 100644 pkg/unikontainers/hypervisors/hvi_test.go diff --git a/pkg/unikontainers/annotations.go b/pkg/unikontainers/annotations.go index 8eb367b57..72202e1be 100644 --- a/pkg/unikontainers/annotations.go +++ b/pkg/unikontainers/annotations.go @@ -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 diff --git a/pkg/unikontainers/annotations_test.go b/pkg/unikontainers/annotations_test.go index 91bff5584..25062da1d 100644 --- a/pkg/unikontainers/annotations_test.go +++ b/pkg/unikontainers/annotations_test.go @@ -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 { diff --git a/pkg/unikontainers/hypervisors/hvi.go b/pkg/unikontainers/hypervisors/hvi.go new file mode 100644 index 000000000..16a59ef8f --- /dev/null +++ b/pkg/unikontainers/hypervisors/hvi.go @@ -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=[,serial=] (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 +} diff --git a/pkg/unikontainers/hypervisors/hvi_test.go b/pkg/unikontainers/hypervisors/hvi_test.go new file mode 100644 index 000000000..81dfb851b --- /dev/null +++ b/pkg/unikontainers/hypervisors/hvi_test.go @@ -0,0 +1,259 @@ +// 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 ( + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "github.com/urunc-dev/urunc/pkg/unikontainers/types" +) + +const testHviBinary = "/usr/bin/hvi" + +func TestHviBuildExecCmd_MissingKernel(t *testing.T) { + t.Parallel() + + h := &HVI{binary: HviBinary, binaryPath: testHviBinary} + _, err := h.BuildExecCmd(types.ExecArgs{}, &fakeUnikernel{}) + assert.Error(t, err) + assert.Contains(t, err.Error(), "kernel path is required") +} + +func TestHviBuildExecCmd_TooManyBlockDevices(t *testing.T) { + t.Parallel() + + h := &HVI{binary: HviBinary, binaryPath: testHviBinary} + args := types.ExecArgs{ + UnikernelPath: testKernelPath, + Seccomp: true, + } + ukernel := &fakeUnikernel{ + blockCli: []types.MonitorBlockArgs{ + {Path: "/dev/disk1"}, + {Path: "/dev/disk2"}, + {Path: "/dev/disk3"}, + {Path: "/dev/disk4"}, + {Path: "/dev/disk5"}, + }, + } + _, err := h.BuildExecCmd(args, ukernel) + assert.Error(t, err) + assert.Contains(t, err.Error(), "hvi supports at most 4 block devices") +} + +func TestHviBuildExecCmd(t *testing.T) { + t.Parallel() + + h := &HVI{ + binary: HviBinary, + binaryPath: testHviBinary, + } + + testCases := []struct { + name string + args types.ExecArgs + unikernel types.Unikernel + expected []string + }{ + { + name: "kernel, memory, vcpus, cmdline", + args: types.ExecArgs{ + UnikernelPath: testKernelPath, + MemSizeB: 512 * 1024 * 1024, + VCPUs: 2, + Command: "panic=-1 console=ttyS0", + Seccomp: true, + }, + unikernel: &fakeUnikernel{}, + expected: []string{ + testHviBinary, "boot", + "--kernel", testKernelPath, + "--mem-mib", "512", + "--cpus", "2", + "--cmdline", "panic=-1 console=ttyS0", + }, + }, + { + name: "memory below 1 MiB defaults to DefaultMemory", + args: types.ExecArgs{ + UnikernelPath: testKernelPath, + MemSizeB: 1024, // < 1 MiB -> bytesToMiB is 0 -> DefaultMemory (256) + Seccomp: true, + }, + unikernel: &fakeUnikernel{}, + expected: []string{ + testHviBinary, "boot", + "--kernel", testKernelPath, + "--mem-mib", "256", + }, + }, + { + name: "tap networking with mac", + args: types.ExecArgs{ + UnikernelPath: testKernelPath, + Net: types.NetDevParams{ + TapDev: "tap0", + MAC: "52:54:00:12:34:56", + }, + Seccomp: true, + }, + unikernel: &fakeUnikernel{}, + expected: []string{ + testHviBinary, "boot", + "--kernel", testKernelPath, + "--net-tap", "tap0", + "--net-mac", "52:54:00:12:34:56", + }, + }, + { + name: "mac ignored when tap device is empty", + args: types.ExecArgs{ + UnikernelPath: testKernelPath, + Net: types.NetDevParams{ + MAC: "52:54:00:12:34:56", + }, + Seccomp: true, + }, + unikernel: &fakeUnikernel{}, + expected: []string{ + testHviBinary, "boot", + "--kernel", testKernelPath, + }, + }, + { + name: "block devices and disks with serial", + args: types.ExecArgs{ + UnikernelPath: testKernelPath, + Seccomp: true, + }, + unikernel: &fakeUnikernel{ + blockCli: []types.MonitorBlockArgs{ + {Path: "/path/to/rootfs.raw", ID: "rootfs"}, + {Path: "/path/to/data.raw"}, + {ExactArgs: []string{"--disk", "path=/custom.raw,readonly=on"}}, + }, + }, + expected: []string{ + testHviBinary, "boot", + "--kernel", testKernelPath, + "--disk", "path=/path/to/rootfs.raw,serial=rootfs", + "--disk", "path=/path/to/data.raw", + "--disk", "path=/custom.raw,readonly=on", + }, + }, + { + name: "initramfs from args and extra monitor cli", + args: types.ExecArgs{ + UnikernelPath: testKernelPath, + InitrdPath: "/boot/initrd.cpio", + Seccomp: true, + }, + unikernel: &fakeUnikernel{ + monitorCli: types.MonitorCliArgs{ + ExtraInitrd: "/extra/initrd.cpio", + }, + }, + expected: []string{ + testHviBinary, "boot", + "--kernel", testKernelPath, + "--initramfs", "/boot/initrd.cpio", + }, + }, + { + name: "initramfs fallback to extra monitor cli when args initrd is empty", + args: types.ExecArgs{ + UnikernelPath: testKernelPath, + Seccomp: true, + }, + unikernel: &fakeUnikernel{ + monitorCli: types.MonitorCliArgs{ + ExtraInitrd: "/extra/initrd.cpio", + }, + }, + expected: []string{ + testHviBinary, "boot", + "--kernel", testKernelPath, + "--initramfs", "/extra/initrd.cpio", + }, + }, + { + name: "virtiofs shared filesystem", + args: types.ExecArgs{ + UnikernelPath: testKernelPath, + Sharedfs: types.SharedfsParams{ + Type: "virtiofs", + }, + Seccomp: true, + }, + unikernel: &fakeUnikernel{}, + expected: []string{ + testHviBinary, "boot", + "--kernel", testKernelPath, + "--fs", "tag=fs0,socket=/tmp/vhostqemu", + }, + }, + { + name: "disabled seccomp emits --no-sandbox", + args: types.ExecArgs{ + UnikernelPath: testKernelPath, + Seccomp: false, + }, + unikernel: &fakeUnikernel{}, + expected: []string{ + testHviBinary, "boot", + "--kernel", testKernelPath, + "--no-sandbox", + }, + }, + { + name: "extra other args forwarded verbatim", + args: types.ExecArgs{ + UnikernelPath: testKernelPath, + Seccomp: true, + }, + unikernel: &fakeUnikernel{ + monitorCli: types.MonitorCliArgs{ + OtherArgs: []string{"--trace-io", "/tmp/trace.log"}, + }, + }, + expected: []string{ + testHviBinary, "boot", + "--kernel", testKernelPath, + "--trace-io", "/tmp/trace.log", + }, + }, + } + + for _, tc := range testCases { + t.Run(tc.name, func(t *testing.T) { + t.Parallel() + + out, err := h.BuildExecCmd(tc.args, tc.unikernel) + require.NoError(t, err) + assert.Equal(t, tc.expected, out) + }) + } +} + +func TestHviSupportsSharedfs(t *testing.T) { + t.Parallel() + + h := &HVI{} + assert.True(t, h.SupportsSharedfs("virtio"), "hvi should support virtio sharedfs") + assert.False(t, h.SupportsSharedfs("9p"), "hvi should not support 9p sharedfs") + assert.False(t, h.SupportsSharedfs(""), "hvi should not support empty sharedfs type") +} diff --git a/pkg/unikontainers/hypervisors/hyperlight_test.go b/pkg/unikontainers/hypervisors/hyperlight_test.go index 591bdf964..f49cc1bee 100644 --- a/pkg/unikontainers/hypervisors/hyperlight_test.go +++ b/pkg/unikontainers/hypervisors/hyperlight_test.go @@ -186,7 +186,7 @@ func TestHyperlightBuildExecCmd(t *testing.T) { func TestHyperlightUsesTUNTAP(t *testing.T) { t.Parallel() assert.False(t, (&Hyperlight{}).UsesTUNTAP(), "hyperlight-unikraft opens the guest's sockets itself, with no tap") - for _, tap := range []types.VMM{&Qemu{}, &Firecracker{}, &CloudHypervisor{}, &HVT{}, &SPT{}, &Hedge{}} { + for _, tap := range []types.VMM{&Qemu{}, &Firecracker{}, &CloudHypervisor{}, &HVT{}, &SPT{}, &Hedge{}, &HVI{}} { assert.True(t, tap.UsesTUNTAP(), "%T gets a tap", tap) } } diff --git a/pkg/unikontainers/hypervisors/utils_test.go b/pkg/unikontainers/hypervisors/utils_test.go index 7a8b60471..f90d48cf1 100644 --- a/pkg/unikontainers/hypervisors/utils_test.go +++ b/pkg/unikontainers/hypervisors/utils_test.go @@ -117,6 +117,7 @@ func TestVMMSignalStopRefuseInvalidPid(t *testing.T) { "hvt": &HVT{}, "spt": &SPT{}, "hyperlight": &Hyperlight{}, + "hvi": &HVI{}, } for name, vmm := range vmms { for _, pid := range []int{-1, 0} { diff --git a/pkg/unikontainers/hypervisors/vmm.go b/pkg/unikontainers/hypervisors/vmm.go index f724d6ea8..41d199e1a 100644 --- a/pkg/unikontainers/hypervisors/vmm.go +++ b/pkg/unikontainers/hypervisors/vmm.go @@ -72,6 +72,12 @@ var vmmFactories = map[VmmType]VMMFactory{ return &Hyperlight{binary: binary, binaryPath: binaryPath} }, }, + HviVmm: { + binary: HviBinary, + createFunc: func(binary, binaryPath string, _ bool) types.VMM { + return &HVI{binary: binary, binaryPath: binaryPath} + }, + }, } func NewVMM(vmmType VmmType, monitors map[string]types.MonitorConfig) (vmm types.VMM, err error) { diff --git a/pkg/unikontainers/hypervisors/vmm_test.go b/pkg/unikontainers/hypervisors/vmm_test.go index 8e471c7f3..32b87c547 100644 --- a/pkg/unikontainers/hypervisors/vmm_test.go +++ b/pkg/unikontainers/hypervisors/vmm_test.go @@ -38,6 +38,7 @@ func TestSupportsControlSocket(t *testing.T) { {"spt", &SPT{}, false}, {"hedge", &Hedge{}, false}, {"hyperlight", &Hyperlight{}, false}, + {"hvi", &HVI{}, false}, } for _, tt := range tests { @@ -96,4 +97,12 @@ func TestVMMFactoryNonQemuIgnoresVhost(t *testing.T) { vmm = factory.createFunc(FirecrackerBinary, "/usr/bin/firecracker", true) _, ok = vmm.(*Firecracker) assert.True(t, ok, "factory should return *Firecracker") + + // HVI factory should ignore vhost parameter + factory, exists = vmmFactories[HviVmm] + assert.True(t, exists, "hvi factory should exist") + + vmm = factory.createFunc(HviBinary, "/usr/bin/hvi", true) + _, ok = vmm.(*HVI) + assert.True(t, ok, "factory should return *HVI") } diff --git a/pkg/unikontainers/unikernels/linux.go b/pkg/unikontainers/unikernels/linux.go index 69fc17edc..8f7e01d17 100644 --- a/pkg/unikontainers/unikernels/linux.go +++ b/pkg/unikontainers/unikernels/linux.go @@ -76,7 +76,7 @@ func (l *Linux) CommandString() (string, error) { // TODO: Check under which conditions console should be set to // ttyS0 or ttyAMA0. Currently, we have noticed that FC requires ttyS0 // and Qemu ttyAMA0 for aarch64 while for amd64 both are fine with ttyS0 - if runtime.GOARCH == "arm64" && l.Monitor == "qemu" { + if runtime.GOARCH == "arm64" && (l.Monitor == "qemu" || l.Monitor == "hvi") { consoleStr = "console=ttyAMA0" } else { consoleStr = "console=ttyS0" @@ -181,7 +181,7 @@ func (l *Linux) MonitorBlockCli() []types.MonitorBlockArgs { Path: aBlock.Source, }) } - case "cloud-hypervisor": + case "cloud-hypervisor", "hvi": for _, aBlock := range l.Blk { blkArgs = append(blkArgs, types.MonitorBlockArgs{ ID: aBlock.ID, @@ -216,7 +216,7 @@ func (l *Linux) MonitorCli() types.MonitorCliArgs { extraCliArgs.ExtraInitrd = urunitConfPath } return extraCliArgs - case "firecracker", "cloud-hypervisor": + case "firecracker", "cloud-hypervisor", "hvi": if l.InitrdConf && l.RootFsType != "initrd" { return types.MonitorCliArgs{ ExtraInitrd: urunitConfPath, From 13febcc2fb5def8bf61fc7b057805686f0128fcf Mon Sep 17 00:00:00 2001 From: Nachiket Roy Date: Sat, 14 Nov 2026 17:44:38 +0530 Subject: [PATCH 2/3] feat(config): add default configuration for hvi monitor Add default monitor configuration for hvi (256 MB memory, 1 vCPU) in urunc configuration. Signed-off-by: Nachiket Roy --- pkg/unikontainers/urunc_config.go | 1 + pkg/unikontainers/urunc_config_test.go | 5 +++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/pkg/unikontainers/urunc_config.go b/pkg/unikontainers/urunc_config.go index eead804b4..c2763b0fd 100644 --- a/pkg/unikontainers/urunc_config.go +++ b/pkg/unikontainers/urunc_config.go @@ -152,6 +152,7 @@ func defaultMonitorsConfig() map[string]types.MonitorConfig { "firecracker": {DefaultMemoryMB: defaultMonitorMemoryMB, DefaultVCPUs: defaultMonitorVCPUs}, "cloud-hypervisor": {DefaultMemoryMB: defaultMonitorMemoryMB, DefaultVCPUs: defaultMonitorVCPUs}, "hyperlight-unikraft": {DefaultMemoryMB: defaultMonitorMemoryMB, DefaultVCPUs: defaultMonitorVCPUs}, + "hvi": {DefaultMemoryMB: defaultMonitorMemoryMB, DefaultVCPUs: defaultMonitorVCPUs}, } } diff --git a/pkg/unikontainers/urunc_config_test.go b/pkg/unikontainers/urunc_config_test.go index 7c6116739..d66cbd050 100644 --- a/pkg/unikontainers/urunc_config_test.go +++ b/pkg/unikontainers/urunc_config_test.go @@ -491,13 +491,14 @@ func TestDefaultConfigs(t *testing.T) { t.Parallel() config := defaultMonitorsConfig() - assert.Len(t, config, 6) + assert.Len(t, config, 7) assert.Contains(t, config, "qemu") assert.Contains(t, config, "hvt") assert.Contains(t, config, "spt") assert.Contains(t, config, "firecracker") assert.Contains(t, config, "cloud-hypervisor") assert.Contains(t, config, "hyperlight-unikraft") + assert.Contains(t, config, "hvi") // Check default values for each monitor for _, hvConfig := range config { @@ -530,7 +531,7 @@ func TestDefaultConfigs(t *testing.T) { assert.Equal(t, testTimestampsPath, config.Timestamps.Destination) assert.False(t, config.Runtime.Libcontainer) assert.False(t, config.Runtime.VAccel) - assert.Len(t, config.Monitors, 6) + assert.Len(t, config.Monitors, 7) assert.Len(t, config.ExtraBins, 1) }) From 1924fe380f62218e84130df68de9d9b7e9393902 Mon Sep 17 00:00:00 2001 From: Nachiket Roy Date: Sat, 14 Nov 2026 17:44:46 +0530 Subject: [PATCH 3/3] docs: document hvi monitor support and installation Document the hvi microVMM across urunc documentation: - Add hvi description and architecture integration in hypervisor-support.md - Add installation instructions from source in installation.md - Add hvi configuration options in configuration.md - Update matrix tables in README.md, index.md, and unikernel-support.md - Add seccomp integration details for hvi in design/seccomp.md - Add hvi to package annotations documentation Signed-off-by: Nachiket Roy --- README.md | 18 +++++++-------- docs/configuration.md | 6 +++++ docs/design/seccomp.md | 2 ++ docs/hypervisor-support.md | 46 ++++++++++++++++++++++++++++++++++++-- docs/index.md | 2 +- docs/installation.md | 13 +++++++++++ docs/package/index.md | 2 +- docs/unikernel-support.md | 13 +++++++++-- 8 files changed, 87 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index da9da6196..d0fffaef3 100644 --- a/README.md +++ b/README.md @@ -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 | +| 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 diff --git a/docs/configuration.md b/docs/configuration.md index 4e0ae4532..d81577be3 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -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 @@ -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 diff --git a/docs/design/seccomp.md b/docs/design/seccomp.md index c139162f6..6d7817de1 100644 --- a/docs/design/seccomp.md +++ b/docs/design/seccomp.md @@ -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' diff --git a/docs/hypervisor-support.md b/docs/hypervisor-support.md index 5a2b8bd66..093491de8 100644 --- a/docs/hypervisor-support.md +++ b/docs/hypervisor-support.md @@ -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 @@ -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 diff --git a/docs/index.md b/docs/index.md index eae5081b4..cf9b13cbb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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) | diff --git a/docs/installation.md b/docs/installation.md index bec5fd2e0..7cc1d6046 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -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`** @@ -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 diff --git a/docs/package/index.md b/docs/package/index.md index de9e6273b..5ceebc83c 100644 --- a/docs/package/index.md +++ b/docs/package/index.md @@ -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. diff --git a/docs/unikernel-support.md b/docs/unikernel-support.md index 61d5fa1f7..a048394f8 100644 --- a/docs/unikernel-support.md +++ b/docs/unikernel-support.md @@ -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 @@ -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