metald: the daemon entrypoint

For Go code, follow the repository Go anti-pattern rules.

Metal specification · Behavior: Metal daemon and API

Purpose

Command metald is the composition root. It loads configuration, creates services, and starts the HTTPS servers.

Command

metald serve [--config path]

The default path is /var/lib/metal/metald.toml. A missing default file is permitted.

Types

Type	Role
options	Resolved runtime settings.
fileConfig	TOML file sections.
tlsConfigurations	TLS for both servers and the node client.

Startup wiring

main.go starts services in this order:

1. Configuration, TLS credentials, and the control and coordination listeners.
2. Directories, patches, systemd, storage stores, and the WireGuard manager.
3. WG Mesh and the optional traffic monitor.
4. Firecracker runtime, SSH session recovery, record validation, and the VM manager.
5. Host service and reconcilers.
6. Atlas trusted keys, then the Atlas and coordination APIs.

• Take listener-api and listener-coordination from the systemd descriptor store before console adoption. TakeFiles returns all remaining descriptors.
• Startup sets systemd status to ready <version>; shutdown sets it to stopping. upgrade-metald.sh waits for ready status.
• The mesh and traffic monitor services are optional and can be nil.
• connectMesh runs on every start when wg_mesh.enabled is true.
• wg_mesh.enabled = false does not disable managed WireGuard peers.
• Both servers require a client certificate from the regional authority.
• The Atlas API also pins tls.atlas_common_name, because node certificates are valid clients.
• The snapshot listener uses the metald.coordination_listen host. That value must be one node IP address, not a wildcard.
• wg_mesh.uplink must name the shared VLAN interface, never its parent.

Config keys

Key	Default	Meaning
metald.base_dir	/var/lib/metal	Host state root.
metald.listen	127.0.0.1:8080	TCP address or unix:/path.
metald.coordination_listen	127.0.0.1:9001	Coordination address.
tls.ca_file	none	Regional authority. Required.
tls.certificate_file	none	Node certificate. Required.
tls.private_key_file	none	Node key. Required.
tls.atlas_common_name	none	Atlas client name. Required.
firecracker.binary_path	/usr/bin/firecracker	Firecracker binary.
firecracker.sockets_dir	/run/metal	API socket links.
firecracker.cpu_template_file	built-in host profile	Explicit CPU template JSON override. See CPU templates.
firecracker.cpu_template_disabled	false	Boot every VM without a CPU template. Atlas sets it from the Metal Server Disable CPU Template check. Cannot be set with cpu_template_file.
jailer.binary_path	/usr/bin/jailer	Jailer binary.
zfs.pool	metal	ZFS pool name.
wireguard.interface	wg0	Underlay interface.
wg_mesh.enabled	true	Enables WG Mesh setup.
wg_mesh.binary_path	/usr/local/bin/atlas-wg-mesh	WG Mesh CLI.
wg_mesh.uplink	none	Interface for Atlas NDP. Required.
wg_mesh.controller_address	none	Atlas tenant-0 mesh address on wg0. VMs of tenant 0 reach it.
traffic_monitor.enabled	true	Enables idle shutdown.
migration.final_delta_mib	512	Delta size that triggers the final snapshot.
migration.transfer_port	9002	Snapshot stream port. Same on every host.
migration.require_guest_ssh	false	Requires a guest SSH handshake before memory snapshot migration source cleanup.

config.example.toml shows the full file.

Runtime loops

• The daemon owns all reconcilers, source streams, and snapshot uploads.
• SIGINT or SIGTERM starts a bounded graceful shutdown.
• Shutdown never stops or destroys guest VMs.

Related

• internal/api/SPEC.md owns the server.
• internal/firecracker/SPEC.md owns the runtime.
• Integration testing describes host setup.