feat(mirage): add dynamic device naming via manifest and annotations #363

codesmith25103 · 2025-12-23T17:11:54Z

Previously, urunc hardcoded MirageOS network interfaces to 'service'
and block devices to 'storage'. This caused failures for unikernels
that defined different interface names in their Solo5 manifest.

This commit introduces dynamic device discovery and mapping:

Parsed .note.solo5.manifest from ELF binary for auto-detection.
Added support for urunc.dev/mirage-net-map annotations.
Updated UnikernelParams to pass binary path and annotations.

This ensures compatibility with diverse MirageOS unikernels.
Fixes: #315

netlify · 2025-12-23T17:12:00Z

✅ Deploy Preview for urunc canceled.

Name	Link
🔨 Latest commit	`44f2f95`
🔍 Latest deploy log	https://app.netlify.com/projects/urunc/deploys/69719a3c8bdc560008c6d9b4

sonarqubecloud · 2025-12-23T17:12:28Z

Quality Gate passed

Issues
3 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

reynir · 2026-01-07T09:52:32Z

pkg/unikontainers/unikernels/mirage.go

+	var manifest Solo5Manifest
+	// Attempt to find the start of the JSON object '{'
+	jsonStart := strings.Index(string(data), "{")
+	if jsonStart == -1 {
+		return nil, fmt.Errorf("invalid manifest format")
+	}
+
+	if err := json.Unmarshal(data[jsonStart:], &manifest); err != nil {
+		return nil, err
+	}
+
+	return &manifest, nil


The note doesn't contain json. See https://github.com/Solo5/solo5/blob/dabc69fd89b8119449ec4088c54b458d4ccc851b/include/mft_abi.h for the format, or https://git.robur.coop/robur/ocaml-solo5-elftool/src/branch/main/lib/solo5_elftool.ml#L73-L146 for code that parses the format.

If you want json you can use solo5-elftool query-manifest $executable assuming solo5-elftool is in $PATH. This adds an external dependency though.

@reynir Thanks for catching this! You are absolutely right
I was incorrectly assuming the manifest section contained JSON, but it is indeed raw binary data as defined in the ABI.

To avoid introducing an external dependency on solo5-elftool, I have rewritten the implementation to parse the binary data natively in Go. The updated parser now:

Follows the layout defined in mft_abi.h.

Correctly handles the C-struct alignment and padding (specifically the 8-byte alignment for the version and device types).

Includes logic to skip the ELF Note header if present.

reynir · 2026-01-07T09:56:22Z

pkg/unikontainers/unikernels/mirage.go

+		mirageID := m.getMirageDeviceName(ifName, "NET_BASIC", "service")
+
+		netOption := fmt.Sprintf("--net:%s=%s", mirageID, ifName)
+		netOption += fmt.Sprintf(" --net-mac:%s=%s", mirageID, mac)


Not sure what the security model is, but you may consider enforcing the constraint that device names are alphanumerical (and at most a fixed length which I don't remember). Otherwise you can inject arbitrary strings here.

I have updated getMirageDeviceName to enforce strict validation:

Alphanumeric Check: The resolved name is validated against a regex (^[a-zA-Z0-9_]+$).

Fallback: If the name contains invalid characters, it safely falls back to the default name (e.g., storage or service) rather than passing the raw string.

Sorry, it doesn't make sense to add a fallback. If the name is invalid then solo5-hvt/solo5-spt will error out parsing the ELF. Even if the ELF was not invalid solo5-hvt/solo5-spt will error out because you just made up a device name that doesn't match the manifest.

Previously, urunc hardcoded MirageOS network interfaces to 'service' and block devices to 'storage'. This caused failures for unikernels that defined different interface names in their Solo5 manifest. This commit introduces dynamic device discovery and mapping: - Parsed .note.solo5.manifest from ELF binary for auto-detection. - Added support for urunc.dev/mirage-net-map annotations. - Updated UnikernelParams to pass binary path and annotations. This ensures compatibility with diverse MirageOS unikernels. Fixes: urunc-dev#315 Signed-off-by: Sankalp <sankalp25103@gmail.com>

reynir · 2026-01-23T07:27:54Z

pkg/unikontainers/unikernels/mirage.go

+	// Heuristic to skip ELF Note Header
+	if len(data) > 12 {
+		var namesz uint32
+		// FIX: Checked error return value (errcheck warning)
+		if err := binary.Read(bytes.NewReader(data[0:4]), binary.LittleEndian, &namesz); err != nil {
+			// If we can't even read 4 bytes, just ignore this check and use offset 0
+		} else {
+			// If namesz is 6 ("Solo5\0"), skip header.
+			// Header = 12 + aligned(namesz)
+			if namesz == 6 {
+				offset = int64(12 + ((namesz + 3) &^ 3))
+			}
+		}
+	}


I don't understand this. Does the ELF library do this or not? It doesn't make sense to maybe do this to me. What is the heuristic exactly?

reynir · 2026-01-23T07:40:58Z

pkg/unikontainers/unikernels/mirage.go

+}
+
+// MftHeader matches the 12-byte header found in the binary.
+// 0x00: Pad/Reserved (4)


The padding is <4 and depends on the note owner and such. I don't think this is right.

reynir · 2026-01-23T07:44:07Z

pkg/unikontainers/unikernels/mirage.go

+	// Sanity Check
+	if header.Version != 1 {
+		return nil, fmt.Errorf("invalid manifest version: %d (expected 1)", header.Version)
+	}


You should check that the number of entries is at least 1 as there is always the RESERVED_FIRST entry.

Also check entries is less than or equal to MFT_MAX_ENTRIES.

reynir · 2026-01-23T07:44:31Z

pkg/unikontainers/unikernels/mirage.go

+		switch entry.Type {
+
+		case mftDevNetBasic:
+			devType = "NET_BASIC"
+		case mftDevBlockBasic:
+			devType = "BLOCK_BASIC"
+		default:
+			devType = fmt.Sprintf("UNKNOWN_%d", entry.Type)
+		}


You forgot the RESERVED_FIRST entry which is always present and the first entry.

reynir · 2026-01-23T07:49:06Z

pkg/unikontainers/unikernels/mirage.go

+const (
+	mftDevBlockBasic = 0
+	mftDevNetBasic   = 1
+	mftNameMax       = 64


Not sure where you got the number 64. It's not right.

reynir · 2026-01-23T07:52:55Z

pkg/unikontainers/unikernels/mirage.go

+	Name  [mftNameMax + 1]byte
+	Pad   [7]byte // Exported to avoid panic in binary.Read
+	Type  uint64
+	Flags uint64


What is Flags?

reynir · 2026-01-23T07:53:26Z

pkg/unikontainers/unikernels/mirage.go

+	Pad   [7]byte // Exported to avoid panic in binary.Read
+	Type  uint64
+	Flags uint64
+	Pad2  [16]byte // Exported to avoid panic in binary.Read


reynir · 2026-01-23T07:54:55Z

pkg/unikontainers/unikernels/mirage.go

+		mirageID := m.getMirageDeviceName(ifName, "NET_BASIC", "service")
+
+		netOption := fmt.Sprintf("--net:%s=%s", mirageID, ifName)
+		netOption += fmt.Sprintf(" --net-mac:%s=%s", mirageID, mac)


Sorry, it doesn't make sense to add a fallback. If the name is invalid then solo5-hvt/solo5-spt will error out parsing the ELF. Even if the ELF was not invalid solo5-hvt/solo5-spt will error out because you just made up a device name that doesn't match the manifest.

reynir · 2026-01-23T07:59:30Z

pkg/unikontainers/unikernels/mirage.go

+		}
+		cleanName := string(entry.Name[:nameLen])
+
+		// Skip empty names (often internal devices)


There are no such thing as internal devices. Empty names are disallowed.

reynir · 2026-01-23T08:02:44Z

pkg/unikontainers/unikontainers.go

+	monitorRootfsDirName     = "monRootfs"
+	containerRootfsMountPath = "/cntrRootfs"


This change is unrelated. It would be helpful to me if unrelated changes were kept out of this PR

cmainas added the ok-to-test label Dec 24, 2025

reynir suggested changes Jan 7, 2026

View reviewed changes

codesmith25103 force-pushed the Issue315 branch 2 times, most recently from fd0bf6f to 3844f3c Compare January 21, 2026 18:00

codesmith25103 force-pushed the Issue315 branch from 3844f3c to 44f2f95 Compare January 22, 2026 03:32

codesmith25103 requested a review from reynir January 22, 2026 04:01

reynir suggested changes Jan 23, 2026

View reviewed changes

		monitorRootfsDirName = "monRootfs"
		containerRootfsMountPath = "/cntrRootfs"

feat(mirage): add dynamic device naming via manifest and annotations #363

Are you sure you want to change the base?

feat(mirage): add dynamic device naming via manifest and annotations #363

Conversation

codesmith25103 commented Dec 23, 2025

Uh oh!

netlify bot commented Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for urunc canceled.

Uh oh!

sonarqubecloud bot commented Dec 23, 2025

Quality Gate passed

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!

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

netlify bot commented Dec 23, 2025 •

edited

Loading