fix: use annotation for MirageOS net device name by pocopepe · Pull Request #690 · urunc-dev/urunc

pocopepe · 2026-05-16T19:40:01Z

Description

mirageos unikernels declare their network device names at build time through the solo5 manifest. the problem was urunc always hardcoded "service" as the device name, so if you built a unikernel with a different name it would just fail.
i added a new annotation com.urunc.unikernel.netDev so image builders can set the name at build time and urunc picks it up at runtime. if the annotation isn't there it falls back to "service" so existing images still work.

block device naming and multi network support i left for follow up prs as discussed.

Related issues

Fixes Support multiple block and network devices over Solo5/MirageOS #315

How was this tested?

go test ./pkg/unikontainers/unikernels/... -v -run TestMirageNetDevName

=== RUN   TestMirageNetDevName
=== RUN   TestMirageNetDevName/uses_net_device_name_from_annotation
=== PAUSE TestMirageNetDevName/uses_net_device_name_from_annotation
=== RUN   TestMirageNetDevName/falls_back_to_service_when_annotation_is_absent
=== PAUSE TestMirageNetDevName/falls_back_to_service_when_annotation_is_absent
=== CONT  TestMirageNetDevName/uses_net_device_name_from_annotation
=== CONT  TestMirageNetDevName/falls_back_to_service_when_annotation_is_absent
--- PASS: TestMirageNetDevName (0.00s)
    --- PASS: TestMirageNetDevName/uses_net_device_name_from_annotation (0.00s)
    --- PASS: TestMirageNetDevName/falls_back_to_service_when_annotation_is_absent (0.00s)
PASS
ok      github.com/urunc-dev/urunc/pkg/unikontainers/unikernels (cached)

LLM usage

Claude Sonnet 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 · 2026-05-16T19:40:07Z

✅ Deploy Preview for urunc canceled.

Name	Link
🔨 Latest commit	`1fd8c85`
🔍 Latest deploy log	https://app.netlify.com/projects/urunc/deploys/6a6302c74a06e40008e95524

cmainas · 2026-05-18T08:29:07Z

Hello @pocopepe ,

this is not enough testing for such PR. You need to build a mirage unikernel with multiple network interfaces and then spawn it with urunc again with multiple network interfaces.

pocopepe · 2026-05-18T12:26:29Z

My bad, I just tested it with a mirage unikernel built to declare a non default net device name being eth0 being neteth0:fix and another with no annotation specified neteth0:bug.

With the annotation:

$ sudo nerdctl run --rm --runtime io.containerd.urunc.v2 neteth0:fix
WARN[0000] cannot set cgroup manager to "systemd" for runtime "io.containerd.urunc.v2"
            |      ___|
  __|  _ \  |  _ \ __ \
\__ \ (   | | (   |  ) |
____/\___/ _|\___/____/
Solo5: Bindings version v0.10.1
Solo5: Memory map: 268 MB addressable:
...
Usage: neteth0 [--help] [OPTION]…
neteth0: unknown option '--ipv4' unknown option '--ipv4-gateway'
Solo5: solo5_exit(64) called

solo5 accepts --net:eth0=... and boots

Without the annotation:

$ sudo nerdctl run --rm --runtime io.containerd.urunc.v2 neteth0:bug
WARN[0000] cannot set cgroup manager to "systemd" for runtime "io.containerd.urunc.v2"
solo5-hvt: Resource not declared in manifest: 'service'
solo5-hvt: Resource not declared in manifest: 'service'
solo5-hvt: Invalid option: `--net:service=tap0_urunc'

urunc defaults to the old hardcoded service and solo5 rejects since the manifest only declares eth0. That's exactly the bug this PR fixes.
Also the pr only focuses on task 1 as mentioned in the description. If this works for you, I'm happy to extend it for block scope and multi interface handling

cmainas · 2026-05-18T12:37:46Z

Thank you @pocopepe for the test. Would it be possible to share the image you built? Also, a small note: If the PR does not entirely fix an issue, you can mention the issue as related, but do not use "Fixes".

pocopepe · 2026-05-18T13:15:40Z

@cmainas sorry, I assumed Fixes was part of the default template, new to the repo conventions. happy to amend the commit and update the pr description to use Related instead, want me to do that now?

Pushed images:

reynir · 2026-05-20T07:40:30Z

 	if data.Net.Mask != "" {
 		m.Net.Address = "--ipv4=" + data.Net.IP + "/24"
 		m.Net.Gateway = "--ipv4-gateway=" + data.Net.Gateway
 	}


In Mirage you can "group" parameters to network devices. What this effectively means is that you can add a prefix to the command line options (often the interface name). An example is for an interface management you'd often add a group management and this would produce command line options --management-ipv4, --management-ipv4-gateway etc. Now, since a recent release of Mirage interfaces will by default use DHCP to acquire this information if it was not presented at boot time (or statically configured) instead of using a silly default of 10.0.0.2/24 and 10.0.0.1 as ipv4 and ipv4-gateway respectively.

So to configure extra interfaces there's no good way to do it, but I think a decent heuristic is for each interface that is not called "service" to use data.NetDevName as the group.

Finally, you can construct unikernels in whatever way you want so you are never guaranteed that the unikernel accepts these options.

yeah makes sense, pushed it as a new commit

Can we add this as a comment to explain the cli argument construction? It is useful information.

cmainas

Hello @pocopepe ,

thank you for the changes. I have added some comments, but overall it looks good.

Also thank you @reynir for the patience and reviewing PRs related to this issue.

cmainas · 2026-06-02T09:23:14Z

 	case "hvt", "spt":
-		netOption := "--net:service=" + ifName
-		netOption += " --net-mac:service=" + mac
+		name := m.netDevName


No reason for this assignment.

cmainas · 2026-06-02T09:27:08Z

 	if data.Net.Mask != "" {
 		m.Net.Address = "--ipv4=" + data.Net.IP + "/24"
 		m.Net.Gateway = "--ipv4-gateway=" + data.Net.Gateway
 	}


Can we add this as a comment to explain the cli argument construction? It is useful information.

cmainas · 2026-06-02T09:29:10Z

 	annotBlock         = "com.urunc.unikernel.block"
 	annotBlockMntPoint = "com.urunc.unikernel.blkMntPoint"
 	annotMountRootfs   = "com.urunc.unikernel.mountRootfs"
+	annotNetDev        = "com.urunc.unikernel.netDev"


Since this is Solo5 specific, I would suggest to add a Solo5 prefix (e.g. Solo5NetDevName).

Prefixed the Go identifiers as suggested. I'm assuming you want the annotation key to stay as com.urunc.unikernel.netDev?

Actually, I meant the annotation key to have a prefix

cmainas · 2026-06-02T09:29:43Z

 	Block            string `json:"com.urunc.unikernel.block,omitempty"`
 	BlkMntPoint      string `json:"com.urunc.unikernel.blkMntPoint,omitempty"`
 	MountRootfs      string `json:"com.urunc.unikernel.mountRootfs"`
+	NetDev           string `json:"com.urunc.unikernel.netDev,omitempty"`


See https://github.com/urunc-dev/urunc/pull/690/changes#r3340122661

cmainas · 2026-06-24T11:25:47Z

Hello @pocopepe ,

just for clarification, I meant that we need to prefix the annotation key and not the struct filed name with the Solo5 prefix.

pocopepe · 2026-07-13T15:49:48Z

Hey @cmainas , sorry about the delay. I've pushed the latest changes per requirement, and fixed it accordingly on my block devices pr as well

cmainas · 2026-07-22T08:42:48Z

Hello @pocopepe ,

thank you for the changes. Everything looks good. Can you rebase over main and squash the commits so we can merge this?

I have also tested it adding the annotation in harbor.nbfc.io/nubificus/urunc/net-spt-mirage:latest and it worked well (failed to execute, but that was the intend). In the meantime, I will try to create a mirage unikernel with a different name for the network device.

cmainas · 2026-07-23T15:09:37Z

Hello @pocopepe ,

I forgot to mention that you should add yourself in https://github.com/urunc-dev/urunc/blob/main/.github/contributors.yaml

Ref: urunc-dev#315 Signed-off-by: viju <avijusanjai@gmail.com>

Signed-off-by: viju <avijusanjai@gmail.com>

pocopepe · 2026-07-24T06:56:28Z

Hi @cmainas,
done, added myself to the list and did a little testing of my own locally, ran it end to end and worked as expected. oh and i fixed the spell check error and applied the same over to block devices (#753), both're rebased up to main. I could get started on the 3rd task of multiple devices once these two are merged.

cmainas

Thank you @pocopepe for all the changes and the PR.

cmainas · 2026-07-24T07:05:28Z

 				annotBlock:         "block1",
 				annotBlockMntPoint: "point1",
 				annotMountRootfs:   "true",
+				annotNetDev:        "management",


It took me a while to understand why this was changed. But all good!

I mean in that way, using that word.

reynir reviewed May 20, 2026

View reviewed changes

namansh70747 mentioned this pull request Jun 2, 2026

Support multiple block and network devices over Solo5/MirageOS #315

Open

cmainas reviewed Jun 2, 2026

View reviewed changes

pocopepe mentioned this pull request Jun 8, 2026

fix: use annotation for MirageOS block device name #753

Open

4 tasks

pocopepe force-pushed the fix/315-mirage-net-annotation branch from a6eebad to 06d5ae1 Compare July 13, 2026 15:05

pocopepe force-pushed the fix/315-mirage-net-annotation branch from 06d5ae1 to b6a0087 Compare July 23, 2026 15:04

cmainas added the ok-to-test label Jul 23, 2026

pocopepe added 2 commits July 24, 2026 10:42

fix: use annotation for MirageOS net device name

3a348ee

Ref: urunc-dev#315 Signed-off-by: viju <avijusanjai@gmail.com>

chore: add to contributors list

1fd8c85

Signed-off-by: viju <avijusanjai@gmail.com>

pocopepe force-pushed the fix/315-mirage-net-annotation branch from b6a0087 to 1fd8c85 Compare July 24, 2026 06:14

cmainas added the takeover label Jul 24, 2026

urunc-bot Bot changed the base branch from main to main-pr690 July 24, 2026 07:04

cmainas approved these changes Jul 24, 2026

View reviewed changes

cmainas merged commit 871d6f3 into urunc-dev:main-pr690 Jul 24, 2026
35 checks passed

Uh oh!

Conversation

pocopepe commented May 16, 2026

Description

Related issues

How was this tested?

LLM usage

Checklist

Uh oh!

netlify Bot commented May 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for urunc canceled.

Uh oh!

cmainas commented May 18, 2026

Uh oh!

pocopepe commented May 18, 2026

Uh oh!

cmainas commented May 18, 2026

Uh oh!

pocopepe commented May 18, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cmainas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cmainas commented Jun 24, 2026

Uh oh!

pocopepe commented Jul 13, 2026

Uh oh!

cmainas commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cmainas commented Jul 23, 2026

Uh oh!

pocopepe commented Jul 24, 2026

Uh oh!

cmainas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

netlify Bot commented May 16, 2026 •

edited

Loading

cmainas commented Jul 22, 2026 •

edited

Loading