self update

Pre-Alpha. This page describes behavior that may change.

Ze can automatically download, verify, and install firmware updates on non-gokrazy deployments. The update cycle: check a version manifest, download the binary, verify its SHA-256, atomically replace the running binary via rename (keeping a .prev backup), and optionally restart.

Platform-aware backend

The update path depends on the platform Ze runs on:

Platform	Backend	Behaviour
Normal Linux	Ze self-update	SHA-256 verified download, atomic rename, .prev rollback, deterministic spread scheduling, maintenance windows, server-side pause, and persisted update history. Everything on this page applies.
Gokrazy appliance	gokrazy-ab	Reports backend: gokrazy-ab, probes the gokrazy management socket for reachability and features, and returns structured "unsupported" responses for the manual firmware operations. Gokrazy owns image updates (atomic A/B partition swap); push images with ze install appliance push. See Appliance.

show system update reports the active backend. The rest of this page describes the normal-Linux self-update backend.

Server setup

ze update-serve

Ze includes a standalone update server for build infrastructure:

ze update-serve --listen :8080

Path	Purpose
GET /version.json	Enhanced manifest (version, sha256, size, paused).
GET /<goos>/<goarch>	Binary download.
GET /<goos>/<goarch>/sha256	Hex SHA-256 digest (text/plain).

The server computes SHA-256 at startup. If the binary changes on disk (rebuild), restart the server.

Pause mechanism

Two mechanisms, ORed together:

• File: create a file named update-paused in the binary's directory. Remove to unpause.
• Signal: send SIGUSR1 to toggle the in-memory pause state.

When paused, the manifest returns "paused": true. Clients with auto-apply stop downloading. Manual commands bypass pause.

Custom server

Any HTTP server returning the manifest JSON works. Required fields:

{
    "version": "26.05.20",
    "sha256": "a1b2c3d4...64hex",
    "size": 52428800,
    "paused": false
}

Optional fields: minimum-version (sequential upgrade enforcement), download-url (override download location, must be HTTPS).

Client configuration

Check-only (default)

system {
    update-check {
        url https://update.example.com/version.json;
    }
}

Daily check, report via show system update and show warnings. No download.

Fleet (automated with scheduling)

system {
    update-check {
        url https://update.example.com/version.json;
        interval 3600;
        auto-apply true;
        spread 1800;
        maintenance-window {
            start 02:00;
            end 06:00;
        }
        restart {
            time 03:00;
        }
    }
}

Check hourly. On new version: wait a random delay up to 30 minutes (spread), download and verify at any time, replace binary only between 02:00 and 06:00, restart at 03:00.

Lab (immediate)

system {
    update-check {
        url https://update.example.com/version.json;
        interval 300;
        auto-apply true;
        spread 0;
        restart {
            immediate;
        }
    }
}

Check every 5 minutes. Download immediately, stage, restart within 5 seconds.

CLI commands

show system update              # Current status
show system update history      # Last 20 update events

update system firmware check       # Trigger immediate version check
update system firmware download    # Download now (bypass spread, window)
update system firmware apply       # Full cycle: download+verify+stage+restart
update system firmware restart     # Restart into staged version
update system firmware rollback    # Restore previous version

Manual commands bypass spread and maintenance window.

Rollback

After a successful update, the previous binary is preserved as <binary>.prev. To roll back:

update system firmware rollback

This renames .prev to the target binary and restarts. After rollback, .prev no longer exists.

Fleet deployment

Spread

Each device computes a deterministic delay from its identity (machine-id or hostname) and the target version string. Default: 3600 seconds (1 hour). A fleet of 100 devices distributes downloads over approximately 1 hour.

Maintenance windows

The maintenance window gates only binary replacement (the rename step). Download and verification proceed at any time. Windows crossing midnight are valid: start 22:00 / end 06:00.

Sequential upgrades

If the server sets minimum-version, devices running an older version are blocked from updating. They must update to the intermediate version first.

Troubleshooting

Symptom	Cause
"not configured"	No url in update-check config.
"auto-apply requires server to provide sha256"	Server manifest missing sha256 field.
"waiting for spread"	Spread delay not elapsed. Use update system firmware download to bypass.
"waiting for maintenance window"	Outside configured window. Use update system firmware apply to bypass.
"paused by server"	Server manifest has paused: true.
"checksum mismatch"	Binary changed on server. Restart ze update-serve.

See also

• System for the update-check configuration block.
• Upgrade and Restart for the manual upgrade workflow.
• Health Checks for update-related warnings.

Adapted from main/docs/guide/self-update.md.