Metal daemon and API
metald is the process on a physical host that accepts Atlas VM requests and applies them to host resources. It also coordinates migration with other Metal hosts. Work on Metal maps the Go packages. This page explains the running process.
Three connection roles
| Connection | Used for | Who can call it |
|---|---|---|
| Control API | VM changes, snapshots, host sync, migration requests. | Atlas client certificate with its pinned common name. |
| Coordination API | Calls between source and destination during migration. | A certificate from the regional authority. |
| Snapshot stream | Direct ZFS transfer between migration hosts. | One-shot mutual TLS with regional authority validation. |
The listeners separate Atlas control calls from host-to-host migration calls. The control listener accepts the pinned Atlas client identity. The coordination listener accepts regional node certificates without a pinned node common name.
Disk snapshots use a separate stream because they carry ZFS data rather than API messages. The control and coordination APIs use TLS 1.3. Read Metal listener security before you expose an address.
The control listener uses the WireGuard address. The coordination listener and the snapshot stream use the migration network. By default, this is the host's private IPv4 address.
Migration traffic already uses TLS, so by default it skips WireGuard. This removes a second encryption layer and the smaller WireGuard MTU from large transfers.
To move migration traffic to WireGuard, follow these steps:
- Click Pause VM Migrations in the Virtual Machine Migration list.
- Wait until no migration is running.
- Turn on Migrate VM over WireGuard in Atlas Settings, under Networking, and save.
- Run Upgrade Metald on each Metal Server.
- Click Resume VM Migrations.
Atlas refuses the change unless migrations are paused and none is running. Atlas uses the new network for the source address at once. Each host moves its listener at its upgrade. Until then, a migration from that host fails before the source locks.
The host firewall admits migration traffic on both networks, so a change needs no firewall update.
What happens at startup
Run metald serve with /var/lib/metal/metald.toml, or pass --config for another file. Startup runs in this order:
- Load TLS credentials, validate the snapshot bind address, and open the control and coordination listeners.
- Prepare WG Mesh when enabled, create host directories, and connect to systemd.
- Open storage and adopt the consoles of running VM units and SSH console sessions.
- Create the VM, host, migration, network, and API services.
- Serve the listeners, start the background workers, and set the systemd status to
ready <version>.
systemd keeps the control and coordination sockets open during a restart. The kernel queues new connections until metald accepts them.
The VM and migration workers check for work every five seconds. The image worker checks every hour. Relevant requests also wake workers. The reconciliation guide explains why a saved request can still be in progress.
Console adoption affects guest survival
At startup, Metal compares running VM units with adopted console handles. If systemd cannot preserve those handles, a later metald exit can stop running guests. See runtime recovery and Metal operations.
Find a listener or record
| Setting | Default | What to check |
|---|---|---|
| Control address | 127.0.0.1:8080 | Installation binds the host WireGuard address. See Atlas access to hosts. A Unix socket is also accepted. |
| Coordination address | 127.0.0.1:9001 | Installation and upgrade_metald bind the host address on the migration network. |
| Snapshot port | 9002 | Binds on the coordination host address, not a wildcard. |
base_dir | /var/lib/metal | Holds VM records and host state. |
zfs.pool | metal | Names the pool Metal uses. Installation selects its device. |
The CA, server certificate, private key, and Atlas client common name are required at startup, even if the default TOML file is absent. The metald specification lists the remaining configuration keys.
Follow a request or failure
The Atlas to Metal contract defines request, retry, unit, and error rules. The Metal API reference lists routes and schemas. Use the request ID in the response to find local logs. Operation IDs connect later host work to the original change.
POST /v1/sync replaces managed host policy and reports capacity and VM states. It is not a guest health check. The host sync guide explains its inputs and freshness.
Metal hides command output and secrets in public errors. Read host logs and the VM's observed phase when an accepted request does not finish. The console guide explains the browser's WebSocket path and the difference between serial and SSH sessions.
What shutdown stops
Shutdown stops listeners and workers, cancels uploads and migration streams, and closes owned connections within a bounded wait. It closes console WebSockets with code 1012 so Atlas can reconnect. It does not stop VM units. Preserved console handles keep guests running.
Source code and tests
- Daemon composition defines startup, listeners, and worker intervals.
- Configuration defines TOML defaults.
- TLS rules define client certificate checks.
- Shutdown releases the daemon's resources.
- TLS tests check certificate validation.