Skip to Content
Building OsStartup Scripts

Startup Scripts

os.startup_scripts erzeugt begrenzte systemd-One-Shot-Arbeit für das resultierende Image. Jeder Eintrag deklariert Shell-Befehl, benötigte Pakete, Ausführungs-User und Ordering-Unit.

Startup Scripts sind root-fähiger Code, sofern run_as nichts anderes sagt. Sie brauchen dieselbe Review wie jedes Installationsskript.

Kanonische Form

{
  "os": {
    "startup_scripts": [
      {
        "name": "write-build-marker",
        "description": "Create a local readiness marker after networking is available.",
        "command": "set -Eeuo pipefail\ninstall -d -m 0755 /var/lib/example\nprintf '%s\\n' ready > /var/lib/example/build-ready",
        "packages": [],
        "run_as": "root",
        "after": "network-online.target"
      }
    ]
  }
}

Die Felder heißen description und command, nicht das Legacy-Feld script. run_as und after nutzen ebenfalls snake_case. after ist ein systemd-Unit-String, kein Array.

Das Schema akzeptiert höchstens 32 Einträge und begrenzte Befehlsgröße. Validierung lehnt leere Befehle und NUL-Bytes ab, macht Shell-Inhalt aber nicht sicher oder idempotent.

Für Retries und partielle Fehler entwerfen

Ein Boot kann unterbroc werden, nachdem schon Nebenwirkungen entstanden sind. Skripte so schreiben, dass ein weiterer Lauf entweder sicher abschließt oder mit klarem, inspizierbarem Zustand exitiert.

Gute Muster:

  • in temporäre Datei schreiben, prüfen, dann atomisch umbenennen;
  • prüfen, ob User, Verzeichnisse oder Config-Einträge schon existieren;
  • install für expliziten Owner und Mode nutzen;
  • set -Eeuo pipefail anwenden und erwartete Nonzero-Ergebnisse gezielt behandeln;
  • begrenzte Netzwerk-Timeouts und endliche Retry-Anzahl; und
  • Readiness-Marker erst nach allen erforderlichen Schritten schreiben.

Verlassen Sie sich nicht auf sleep als Readiness-Check. Die echte Abhängigkeit prüfen.

Externe Downloads

Vermeiden Sie curl ... | sh. Muss First Boot ein Artefakt laden:

  1. HTTPS mit Zertifikatsprüfung nutzen;
  2. erwartetes Artefakt oder Source-Version pinnen;
  3. kryptografischen Digest oder genehmigte Signatur vor Ausführung prüfen;
  4. Connect- und Total-Timeouts setzen;
  5. bei fehlgeschlagener Verifikation fail closed; und
  6. Credentials oder signierte URLs nicht loggen.

Für wirklich offline oder reproduzierbares Verhalten reviewed Content ins Image oder ein genehmigtes Package-Repository legen statt beim First Boot zu laden.

Geheimnisse

Keine Klartext-Credentials in Rezept, Befehl, URL oder generiertem Marker. Rezept-JSON und Build-Logs sind retained evidence und können für Operatoren sichtbar sein. Genehmigten Deployment-Zeit-Enrollment oder Secret-Delivery-Mechanismus nutzen und resultierendes Credential auf das Ziel scopen.

Ausführungs-Identität

Unprivilegierten Service-Account bevorzugen. Braucht es root, den Befehl auf den kleinsten privilegierten Schritt reduzieren und explizite Datei-Ownership setzen. Bestätigen, dass run_as ein Konto benennt, das vor Unit-Start angelegt wurde.

Verifikation

Ergebnisse testen, nicht nur Unit-Exit-Status:

{
  "type": "file_contains",
  "description": "The startup unit wrote its readiness marker.",
  "params": {
    "path": "/var/lib/example/build-ready",
    "content": "ready"
  }
}

Auch zweiten Boot, nicht verfügbare Abhängigkeit und Recovery nach unterbrochenem Erstlauf testen. Bei Fehler systemctl status und Unit-Journal prüfen.

ServicesImage-lokale User