metald: the daemon entrypoint
For Go code, follow the repository Go anti-pattern rules.
metal SPEC · overview: docs/architecture.md
Purpose
Command metald loads host configuration, creates runtime services, and starts the HTTPS servers. It is the composition root.
Command
metald serve [--config path]The default configuration path is /var/lib/metal/metald.toml. A missing default file is permitted.
Types
| Type | Role |
|---|---|
options | Resolved runtime, listener, TLS, authentication, and base-directory settings. |
fileConfig | TOML sections for Metal and its runtime services. |
tlsConfigurations | TLS settings for the Atlas API, coordination server, and node client. |
Startup wiring
The storage constructor receives the daemon context, pool, image directory, and logger. It returns the pool, VM, image, and snapshot stores.
The network constructor receives optional mesh and traffic monitor services. The VM manager receives the runtime, network, storage, snapshot, optional traffic monitor, and logger services.
The host service receives an optional mesh service, WireGuard, image, VM, storage, and reconciler services. The API receives this service as one dependency.
Both servers require a client certificate from the regional authority. The Atlas API also pins tls.atlas_common_name, because a node certificate is valid for client use on the coordination API.
The source starts a one-shot mutual-TLS listener on migration.transfer_port for each snapshot. The listener uses the coordination address host and port 9002 by default, so metald.coordination_listen needs one node IP address and not a wildcard host. The destination verifies the source WireGuard IP before it receives the stream.
connectMesh runs on every start when wg_mesh.enabled is true. Each VM reconciliation calls Network.Ensure to restore and update its network.
wg_mesh.enabled = false does not disable managed WireGuard peers.
wg_mesh.uplink has no default. The Atlas WG Mesh NDP hook and its proxy NDP entries attach to this interface, so it must name the shared VLAN itself and never its parent. Only the controller knows which interface carries Atlas NDP, so metald requires the name.
Config keys
| Key | Default | Meaning |
|---|---|---|
metald.base_dir | /var/lib/metal | Stores machines, images, policies, peers, and staging files. |
metald.listen | 127.0.0.1:8080 | TCP address or unix:/path. |
metald.coordination_listen | 127.0.0.1:9001 | Mutual-TLS node coordination address. |
tls.ca_file | none | Required regional Metal authority certificate. |
tls.certificate_file | none | Required node certificate. |
tls.private_key_file | none | Required node private key. |
tls.atlas_common_name | none | Required common name of the Atlas client certificate. |
firecracker.binary_path | /usr/bin/firecracker | Firecracker binary. |
firecracker.sockets_dir | /run/metal | Short API socket links. |
jailer.binary_path | /usr/bin/jailer | Jailer binary. |
zfs.pool | metal | ZFS pool name. |
wireguard.interface | wg0 | Underlay interface for managed peers and Atlas WG Mesh. |
wg_mesh.enabled | true | Enables Atlas WG Mesh host setup and VM mesh registration. |
wg_mesh.binary_path | /usr/local/bin/atlas-wg-mesh | Atlas WG Mesh CLI. Required. |
wg_mesh.uplink | none | Private network interface that carries Atlas NDP. Required. |
traffic_monitor.enabled | true | Enables VM packet monitoring and idle shutdown. |
migration.final_delta_mib | 512 | Incremental size at or below which the destination stops the source and takes the final snapshot. |
migration.transfer_port | 9002 | Mutual-TLS snapshot stream port. Use the same value on every host in the region. |
See config.example.toml for the complete file format.
Runtime loops
The VM reconciler processes desired VM states. The image reconciler downloads cached images, creates warm artifacts, and removes idle local data. When traffic monitoring is enabled, one traffic listener dispatches each restoration in a separate daemon-owned goroutine.
The daemon owns all reconcilers, source stream processes, and snapshot upload jobs. SIGINT or SIGTERM starts a bounded graceful shutdown. It stops both HTTPS servers, cancels workers, closes console sessions, and closes host services. It does not stop or destroy guest virtual machines.
The daemon writes structured JSON logs. Log records include request and operation correlation fields when the operation comes from the API.
Related
- docs/architecture.md describes the runtime graph.
- internal/api/SPEC.md describes the server.
- internal/firecracker/SPEC.md describes the runtime.
- docs/testing.md describes host setup.