platform: host integration
For Go code, follow the repository Go anti-pattern rules.
internal SPEC · overview: docs/architecture.md
Purpose
Package platform is Metal's boundary to host files, commands, and systemd. It keeps host integration details out of domain packages.
Metal talks to systemd through D-Bus. It does not call the systemctl command.
Types
| Type | Responsibility |
|---|---|
UnitManager | Defines the systemd operations needed by a VM runtime. |
DBus | Implements UnitManager and owns the system-bus connection. |
Status, Result, and Limits | Carry systemd state across the platform boundary. |
FileDescriptorStore | Keeps open file descriptors in systemd across a restart of this service. |
Host commands
Run is for commands where the caller only needs success or failure. Output is for commands where the caller needs stdout. RunInNetworkNamespace runs one command through ip netns exec and returns stdout. Each function preserves command diagnostics in errors and accepts a context that can stop a running command.
Systemd units
One template unit runs each virtual machine:
Connect opens one system-bus connection and Close releases it. The runtime receives UnitManager, so it does not depend on D-Bus details.
| Operation | Behavior |
|---|---|
| Start and stop | Submit the requested transition and wait for systemd to finish it. A replace operation makes the newest request win. |
| Kill | Sends a signal to the unit's processes. |
| Reset failed | Clears a failed unit. An absent unit is ignored. |
| Status and list | Report units in terms the VM runtime can use. |
| Wait | Waits for a unit to stop and reports an exit code or signal. |
| Set limits | Applies the requested runtime resource limits. |
The context cancels systemd waits and polling. The VM runtime maps the returned unit state to VM state; that mapping belongs in the firecracker package.
File descriptor store
systemd holds file descriptors across a restart or a stop of the service. FileDescriptorStore stores one with FDSTORE=1, removes one with FDSTOREREMOVE=1, and reads the descriptors that systemd returns.
The unit needs NotifyAccess, FileDescriptorStoreMax, and FileDescriptorStorePreserve=yes. Without the notification socket, IsAvailable is false and store operations do nothing.
Without FileDescriptorStorePreserve=yes, systemd releases the descriptors when the service stops.
Related
- docs/vm.md describes the VM state machine.
- internal/firecracker/SPEC.md describes the unit's
ExecStartand runtime state mapping. - docs/host-layout.md lists host unit files and paths.