Skip to content

feat(monitor): add hvi monitor implementation - #1149

Open
Nachiket-Roy wants to merge 3 commits into
urunc-dev:mainfrom
Nachiket-Roy:feat/hvi-vmm
Open

Nachiket-Roy wants to merge 3 commits into
urunc-dev:mainfrom
Nachiket-Roy:feat/hvi-vmm

Conversation

@Nachiket-Roy

Copy link
Copy Markdown
Contributor

Description

Added HVI microVMM support to urunc for running Linux unikernels. It introduces the HVI monitor implementation, integrates it with the VMM factory, and adds support for kernel boot parameters, initramfs, memory and vCPU configuration, TAP networking, block devices, virtiofs, and seccomp sandboxing.

It also adds HVI-specific annotation validation, default configuration and deployment support, end-to-end test coverage, and documentation for installation and usage.

Related issues

How was this tested?

Performed manual end-to-end verification of the OCI container lifecycle using urunc with the new HVI VMM integration.

  • Built urunc using make urunc_dynamic.
  • Configured an OCI bundle with an uncompressed Linux kernel (vmlinux) and HVI-specific annotations.
  • Ran urunc inside an isolated user namespace using unshare.
  • Verified the complete container lifecycle:
    • create: Resolved HVI annotations, prepared mounts and device nodes, and recorded container state.
    • start: Successfully invoked the HVI VMM and transitioned the container to running.
    • kill: Successfully dispatched SIGKILL through HVI.Signal.
    • delete: Successfully cleaned up the monitor rootfs, mounts, and container state.

All four lifecycle operations completed successfully.

LLM usage

Used Gemini 3.8 and Opus 4.6

Checklist

  • I have read the contribution guide.
  • The linter passes locally (make lint).
  • The e2e tests of at least one tool pass locally (make test_ctr, make test_nerdctl, make test_docker, make test_crictl).
  • If LLMs were used: I have read the llm policy.

@netlify

netlify Bot commented Oct 21, 2026 •

Copy link
Copy Markdown

👷 Deploy request for urunc pending review.

Visit the deploys page to approve it

Name Link
🔨 Latest commit 1924fe3

@cmainas cmainas left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you @Nachiket-Roy,

a few comments:

  • Have you tried this e2e with an image targetting hvi?
  • We add a new test case that uses hvi, but we do not update the CI to install hvi.
  • The urunc-deploy installation scripts install hvi which does not exist in the container where the script runs.
  • The hvi BuildExecCmd calls unikernel implementations and no unikernel implementation has been updated with hvi.
  • We need to add an entry for hvi in https://github.com/urunc-dev/urunc/blob/main/docs/design/seccomp.md

Comment thread docs/hypervisor-support.md Resolved
Comment thread pkg/unikontainers/hypervisors/hvi.go Resolved
Comment thread docs/variables/versions.yml Resolved
Comment thread docs/hypervisor-support.md Resolved
Comment thread pkg/unikontainers/hypervisors/hvi.go Resolved
Comment thread README.md Resolved
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 <nachiket.roy.2@gmail.com>
Add default monitor configuration for hvi (256 MB memory, 1 vCPU) in
urunc configuration.

Signed-off-by: Nachiket Roy <nachiket.roy.2@gmail.com>
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 <nachiket.roy.2@gmail.com>
@Nachiket-Roy

Nachiket-Roy commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor Author

Hey @cmainas Thanks for the issues. I have fixed majority of them. Please take a look again

  • Have you tried this e2e with an image targetting hvi?
  • We add a new test case that uses hvi, but we do not update the CI to install hvi.

Removed until Nubificus publishes it.

  • The urunc-deploy installation scripts install hvi which does not exist in the container where the script runs.

Yes, removed since it is build from source

  • The hvi BuildExecCmd calls unikernel implementations and no unikernel implementation has been updated with hvi.

it was added in later commit. I have fixed the commit order

Done

@cmainas

cmainas commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

Hello @Nachiket-Roy ,

Hey @cmainas Thanks for the issues. I have fixed majority of them. Please take a look again

  • Have you tried this e2e with an image targetting hvi?
  • We add a new test case that uses hvi, but we do not update the CI to install hvi.

Removed until Nubificus publishes it.

Please verify this e2e. Creating an image that targets hvi is a few commands...

@Nachiket-Roy

Nachiket-Roy commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor Author

Please verify this e2e. Creating an image that targets hvi is a few commands...

Done. Image- ghcr.io/nachiket-roy/busybox-hvi-linux-raw:latest

logs:

[2026-11-16T18:17:32Z INFO  virtiofsd] Waiting for vhost-user socket connection...
booting /cntrRootfs/.boot/kernel with 256 MiB ...
[hvi] virtio-net: tap tap0_urunc
[hvi] virtio-fs[0]: "fs0" on /tmp/vhostqemu
[2026-11-16T18:17:32Z INFO  virtiofsd] Client connected, servicing requests
[hvi] 1 vCPU(s)  vmlinux entry@0x1000123
[hvi] seccomp: on (vmm 48 syscalls, vcpu 40, trap on mismatch; open is refused)
[    0.000000] Linux version 6.12.36 (@b702d6ef5e06) (gcc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0, GNU ld (GNU Binutils for Ubuntu) 2.38) #1 SMP Sun Jul 20 19:15:21 UTC 2025
[    0.000000] Command line: panic=-1 console=ttyS0 root=fs0 rw rootfstype=virtiofs ip=10.4.0.2::10.4.0.1:255.255.255.0:urunc:eth0:off retain_initrd URUNIT_CONFIG=/sys/firmware/initrd init=/urunit console=ttyS0 -- /bin/sh
[    0.000000] Disabled fast string operations
[    0.000000] BIOS-provided physical RAM map:
[    0.000000] BIOS-e820: [mem 0x0000000000000000-0x000000000009fbff] usable
[    0.000000] BIOS-e820: [mem 0x0000000000100000-0x000000000fffffff] usable
[    0.000000] NX (Execute Disable) protection: active
[    0.000000] APIC: Static calls initialized
[    0.000000] DMI not present or invalid.
[    0.000000] Hypervisor detected: KVM
[    0.000000] kvm-clock: Using msrs 4b564d01 and 4b564d00
[    0.000000] kvm-clock: using sched offset of 22180971 cycles
[    0.000007] clocksource: kvm-clock: mask: 0xffffffffffffffff max_cycles: 0x1cd42e4dffb, max_idle_ns: 881590591483 
...
[    0.065013] smp: Brought up 1 node, 1 CPU
[    0.065424] smpboot: Total of 1 processors activated (5376.00 BogoMIPS)
[    0.066061] Memory: 229868K/261752K available (12288K kernel code, 1050K rwdata, 2336K rodata, 1148K init, 2576K bss, 29928K reserved, 0K cma-reserved)
[    0.067351] devtmpfs: initialized
[    0.067417] x86/mm: Memory block size: 128MB
[    0.067981] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 7645041785100000 ns
[    0.068803] futex hash table entries: 256 (order: 2, 16384 bytes, linear)
[    0.069627] NET: Registered PF_NETLINK/PF_ROUTE protocol family
[    0.070361] audit: initializing n
5, rootpath=
[    0.149458] RAMDISK: Couldn't find valid RAM disk image starting at 0.
[    0.150520] VFS: Mounted root (virtiofs filesystem) on device 0:19.
[    0.151511] devtmpfs: error mounting -2
[    0.151977] Freeing unused kernel image (initmem) memory: 1148K
[    0.152271] Write protecting the kernel read-only data: 16384k
[    0.154052] Freeing unused kernel image (rodata/data gap) memory: 1760K
[    0.154382] Run /urunit as init process
Warning: No configuration for block mounts
/bin/sh: can't access tty; job control turned off
/ # 

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add support for hvi vmm

2 participants