Flags, Ausgabe & Exit-Codes

Diese Regeln gelten für jeden ironflock-Befehl, und ein Skript kann sich auf sie verlassen. Die Seite jedes Befehls nennt nur, was der Befehl hinzufügt.

Eine Befehlszeile hat eine von zwei Formen:

ironflock <group> <verb> [flags]      ironflock agent install -c device.flock
ironflock <verb> [flags]              ironflock version

Die Gruppe ist das Produkt: agent für den Geräte-Agenten, appliance für die IronFlock-Appliance, os für IronFlockOS. Ein Verb bedeutet in jeder Gruppe dasselbe. Befehle, die die Maschine als Ganzes betreffen, haben keine Gruppe. ironflock und ironflock <group> ohne Verb geben ihre Hilfe aus. Kein Befehl nimmt Positionsargumente an, außer seine Seite sagt es; alles andere ist ein Flag. login und device sind reservierte Namen: Sie antworten mit Exit-Code 2, dass sie reserviert sind.

Globale Flags

Jeder Befehl akzeptiert diese Flags. Alle außer --help dürfen vor oder nach dem Namen des Befehls stehen: ironflock --json version und ironflock version --json sind dasselbe.

Flags mit festen Namen

Ein Flag-Name bedeutet in jedem Befehl, der das Flag hat, dasselbe. -c und -d sind neben -h die einzigen kurzen Flags.

Download-Basis und Proxy

Die Download-Basis kommt aus --download-base, dann aus der Umgebungsvariablen IRONFLOCK_DL_BASE, sonst ist sie https://instance-registry.ironflock.com/dl. Ist keines von beiden gesetzt, nehmen agent install, doctor, os install und os update vor der Cloud den Download-Spiegel der Appliance, die die .flock-Datei des Geräts nennt (Geräte einer IronFlock-Appliance).

Der Proxy kommt aus den Flags, dann aus HTTP_PROXY, HTTPS_PROXY und NO_PROXY (oder ihren kleingeschriebenen Formen). agent configure ist die Ausnahme: Es ändert den Proxy des Geräts allein mit seinen Flags, und die Umgebung des Befehls ändert dort nichts. Eine Proxy-URL sieht aus wie http://proxy.example.com:3128; https:// und socks5:// funktionieren auch, und eine URL ohne Schema gilt als http://. Verlangt der Proxy eine Anmeldung, nennt die URL den Benutzer, wie in http://[email protected]:3128, und --proxy-password-file liefert das Passwort (siehe Secrets). Für Geräte hinter einem Proxy siehe Hinter einem Unternehmens-Proxy.

Ausgabe und JSON

stdout enthält das Ergebnis und sonst nichts. Das ist ein kurzer Text für einen Menschen oder mit --json genau ein JSON-Objekt in einer Zeile. Auch --help geht auf stdout. Die einzige Ausnahme ist agent logs, dessen Ergebnis das Log ist: Mit --json schreibt es ein JSON-Objekt pro Zeile des Logs.

stderr enthält alles andere: Fortschritt, die Ausgabe der Werkzeuge, die ein Befehl ausführt (apt, der Docker-Installer), Warnungen, Fragen und Fehler.

So erhält eine Umleitung oder eine Befehlssubstitution nur das Ergebnis, und ein Skript, das keine Meldungen will, leitet stderr um:

# Das Ergebnis als Text in einer Datei; Fortschritt und Warnungen erscheinen weiter im Terminal
ironflock status > result.txt
 
# Das Ergebnis als JSON in einer Shell-Variablen, ohne die Meldungen auf stderr
result=$(ironflock status --json 2>/dev/null)

Feldnamen in JSON sind snake_case. Ein Ergebnis hat das Feld action, wenn der Befehl etwas geändert hat, zum Beispiel "installed", "configured" oder "removed". Felder kommen mit der Zeit hinzu, und keines wird innerhalb einer Hauptversion umbenannt oder entfernt. Ein Programm, das ein Ergebnis liest, ignoriert die Felder, die es nicht kennt. Bei mehreren Maschinen schreibt --json stattdessen eine Zeile pro Maschine (siehe Entfernte Maschinen über SSH).

Fortschritt

Ein langer Schritt zeigt auf stderr, wie weit er ist: einen Balken an einem Terminal, sonst eine Zeile bei jedem Zehntel. Mit --json erhält stdout weiterhin genau ein JSON-Objekt, das Ergebnis, und stderr erhält den Fortschritt als Ereignisse, ein JSON-Objekt pro Zeile:

{"event":"progress","phase":"writing","done":104857600,"total":412345678}

os install liest die Image-Datei vor dem Neustart zweimal: checking vergleicht ihre SHA-256-Prüfsumme mit dem signierten Katalog, und preparing entpackt das Image einmal, um seine IRONFLOCKOS-Partition zu finden, die .flock-Datei des Geräts und die Netzwerkeinstellungen hineinzulegen und die Prüfsummen dessen zu berechnen, was das Schreiben auf die Festplatte bringt. Am Terminal erscheinen sie als Checking und Preparing.

Ein Ereignis kommt, wenn eine Phase beginnt (done ist 0), immer wenn sich der ganzzahlige Prozentwert ändert, und wenn die Phase abgeschlossen ist (done gleich total). Ein Download, der fortgesetzt wird, springt auf die Bytes, die er schon hat. Andere Zeilen auf stderr, darunter Warnungen, sind Text für einen Menschen: Ein Programm nimmt die Zeilen, die sich als JSON-Objekte parsen lassen, und überspringt den Rest.

Fragen und Bestätigung

Ein Befehl, der die Maschine ändert, sagt zuerst, was er tun wird, und fragt dann:

• Ein Befehl, der etwas entfernt oder überschreibt, sagt zuerst, was verloren geht. Ein Befehl, der installiert, sagt zuerst, was er installieren wird. agent stop sagt zuerst, was das Stoppen des Agenten beendet.
• --yes beantwortet jede Frage des Befehls mit Ja und nimmt den Standard, wo der Befehl eine Auswahl bietet.
• Am Terminal ist bei einer Frage „Ja“ vorausgewählt, sodass Enter allein fortfährt. Bei drei Fragen ist „Nein“ vorausgewählt, sodass Enter allein nichts löscht und nichts entfernt: bei os flash, bevor es ein Laufwerk löscht, bei os flash, bevor es die Datei von --output ersetzt, und bei agent remove.
• os reset verlangt, dass Sie den Namen des Geräts eintippen, und os install den Hostnamen der Maschine. Alles andere, auch Enter allein, beantwortet die Frage mit Nein.
• Was Sie eingetippt haben, bevor eine Frage erschien, wird verworfen. Eine Frage wird beantwortet, nachdem Sie gelesen haben, was der Befehl sagt.
• Esc beantwortet die Frage mit Nein: Der Befehl ändert nichts und endet mit Exit-Code 4. Strg+C bei einer Frage gibt keine Antwort, auch nicht die vorausgewählte: Der Befehl ändert nichts und endet mit Exit-Code 130.

Eine Frage braucht ein Terminal auf stdin und auf stderr. Ohne Terminal (eine Pipe, CI, ein cloud-init-Skript) wartet der Befehl nicht und rät nicht: Er endet mit Exit-Code 4 und sagt, dass --yes bestätigt. Dasselbe gilt mit --json, das nichts fragt. Skripte geben --yes deshalb zusammen mit --json an.

--yes hebt nie eine Ablehnung auf. Wenn ein Befehl ablehnt (Exit-Code 3 oder eine fehlgeschlagene Prüfung), lässt ihn kein Flag weitermachen. Die Seite jedes Befehls listet auf, was er ablehnt. Die einzige Ausnahme ist eine interne Festplatte, die os flash --allow-internal beschreibt, wenn --drive sie nennt.

Über --host erreichen Sie die Fragen, wenn Sie den Befehl an einem Terminal ausführen. Auf mehreren Maschinen gleichzeitig wird niemand gefragt, daher läuft ein Befehl, der fragt, dort nur mit --yes (siehe Entfernte Maschinen über SSH).

Root-Rechte

Ein Befehl, der das System ändert, braucht Root-Rechte. Ohne sie endet er mit Exit-Code 3 und sagt das. Er ruft sudo nicht selbst auf; nur --host tut das, auf der anderen Maschine. os flash nennt dann die einzugebende Befehlszeile mit sudo davor.

Über --host läuft ein Befehl, der Root-Rechte braucht, auf der anderen Maschine über sudo, wenn der SSH-Benutzer nicht root ist.

Secrets

Kein Befehl gibt ein Secret aus: nicht das Secret einer .flock-Datei, keine WLAN-Passphrase, kein Proxy-Passwort, keinen Lizenzschlüssel. Das gilt für stdout, stderr, --json und Fehlermeldungen.

Ein Secret ist nie der Wert eines Flags, wo eine Datei es aufnehmen kann, denn Befehlszeilen erscheinen in ps und im Shell-Verlauf. Ein Proxy-Passwort ist keine Ausnahme:

• Eine Proxy-URL in einem Flag nennt den Benutzer ohne das Passwort: http://[email protected]:3128.
• Eine URL mit Passwort, etwa http://user:password@proxy:3128, ist eine falsche Befehlszeile (Exit-Code 2). Sie wird abgelehnt, bevor irgendetwas läuft, und mit --host, bevor sie an die Maschine geht. Die Fehlermeldung wiederholt sie nicht.
• Das Passwort kommt aus --proxy-password-file: einer Datei oder einer Pipe (/dev/stdin) mit einer Zeile.
• Die Proxy-Variablen der Umgebung, auf die agent install zurückgreift, dürfen ein Passwort enthalten: Sie stehen auf keiner Befehlszeile.

# Das Passwort aus einer Datei
sudo ironflock agent configure --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt
 
# Das Passwort über eine Pipe
sudo ironflock agent configure --proxy-password-file /dev/stdin --yes < proxy-password.txt

Auf einem Gerät, das agent install eingerichtet hat, liegt das Proxy-Passwort dort, wo nur root es liest: in /etc/ironflock/proxy.env (Modus 0600). Die Drop-ins von docker.service und von ironflock-device-agent.service nennen diese Datei und enthalten keine Proxy-Einstellung, sodass systemctl show jedem Benutzer den Namen der Datei verrät und nichts von ihrem Inhalt.

Über --host geht eine .flock-Datei, eine WLAN-Passphrasendatei oder eine Proxy-Passwortdatei, die in einem Flag genannt ist, über die SSH-Verbindung an die andere Maschine, nie auf einer Befehlszeile (siehe Entfernte Maschinen über SSH). Eine Download-Basis mit Anmeldedaten darin endet mit Exit-Code 2, bevor irgendeine Maschine erreicht wird.

Exit-Codes

Ein Fehler ist eine Zeile auf stderr, Error: gefolgt von der Meldung. Auf einen Fehler der Art usage folgt eine Zeile, die das passende --help nennt. Mit --json ist der Fehler das Ergebnis: stdout erhält ein Fehlerobjekt, und stderr erhält keine Fehlerzeile. kind ist eine der Arten aus der Tabelle.

{"error":{"kind":"precondition","message":"the agent is not installed on this machine"}}

Zwei Befehle schreiben ihr Ergebnis und enden trotzdem mit Exit-Code 1. agent update tut das, wenn der Agent auf seiner Version bleibt: Das Ergebnis sagt, warum, und stderr erhält die Zeile Error:. doctor tut das, wenn eine Prüfung fehlgeschlagen ist: Das Ergebnis sagt, welche, und es folgt keine Fehlerzeile. Mit --json schreibt dann keiner der beiden ein Fehlerobjekt: stdout enthält das Ergebnis.

Mit --help ist ein unbekannter Befehl kein Fehler: ironflock os nosuch --help gibt die Hilfe von ironflock os aus, mit Exit-Code 0. Auf mehreren Maschinen endet der Befehl mit dem schlechtesten Exit-Code der Maschinen (siehe Entfernte Maschinen über SSH).

Unterbrechungen

Strg+C, SIGTERM und SIGHUP (wenn das Terminal oder die SSH-Sitzung wegfällt) beenden die meisten Befehle sofort, so wie sie jedes Programm beenden, ohne Fehlerzeile; die Shell sieht 130 (143 nach SIGTERM, 129 nach SIGHUP). Einige Schritte behandeln sie:

• os flash, während es ein Image herunterlädt, schreibt oder zurückliest, und os update, während es ein Bundle herunterlädt und prüft, halten beim nächsten Block an. Sie sagen als Fehler der Art interrupted, was sie zurückgelassen haben, und enden mit 130; os update installiert dann nichts. Sobald os flash den letzten Block zurückgelesen hat, laufen seine abschließenden Schritte zu Ende, und es endet mit 0. Ein zweites Strg+C beendet den Prozess sofort; mit --output kann die .part-Datei zurückbleiben.
• agent logs --follow folgt dem Log bis zu einem solchen Signal und endet dann mit 0.
• agent update hört mit 130 auf, dem Update zu folgen; der Agent macht von selbst weiter.
• os reset nimmt, während es seine Anforderung schreibt, die Anforderung zurück und endet mit 130, und das Gerät startet nicht neu.
• agent configure hält nicht mehr für ein verlorenes Terminal oder eine verlorene SSH-Sitzung an, sobald es begonnen hat, die Maschine zu ändern. Strg+C und SIGTERM beenden es weiterhin sofort.
• os install verhält sich vor und nach seiner Frage unterschiedlich; siehe ironflock os install.

Exit-Codes in einem Skript

Ein Skript gibt --yes an, damit der Befehl nicht an seiner Frage stehen bleibt, und --json für ein Ergebnis, das es lesen kann, und prüft den Exit-Code:

#!/bin/sh
# Den Agenten sich selbst aktualisieren lassen; das JSON-Ergebnis behalten, den Fortschritt auf stderr verwerfen.
result=$(sudo ironflock agent update --yes --json 2>/dev/null)
code=$?
case $code in
  0) echo "agent is current: $result" ;;
  1) echo "agent update failed: $result" ;;
  3) echo "agent update refused on this machine: $result" ;;
  *) echo "agent update ended with exit code $code: $result" ;;
esac

Mit Exit-Code 0 enthält $result das Ergebnis, dessen outcome updated oder current ist. Mit Exit-Code 1 enthält es entweder das Ergebnis, dessen outcome und reason sagen, warum der Agent auf seiner Version bleibt, oder ein Fehlerobjekt. Mit Exit-Code 3 enthält es das Fehlerobjekt.