Installation

Eine Zeile installiert ironflock unter Linux oder macOS. Sie muss als root laufen, weil sie nach /usr/local/bin schreibt. Später bringt ironflock self-update es auf das neueste Release, und ironflock version --check sagt Ihnen, ob ein neueres erschienen ist.

curl -fsSL https://instance-registry.ironflock.com/dl/cli/install.sh | sudo bash

Was die Installationszeile tut

1. Sie ermittelt das System (Linux oder macOS) und die Architektur der Maschine: amd64, arm64 oder 32-Bit-ARM (v5 bis v7) unter Linux, Apple Silicon oder Intel unter macOS. Auf Apple Silicon erhält auch eine Shell, die unter Rosetta 2 läuft, den Build für Apple Silicon.
2. Sie lädt version.txt und das ironflock dieser Version für diese Maschine von https://instance-registry.ironflock.com/dl/cli/ herunter.
3. Sie prüft beides gegen den Release-Schlüssel von IronFlock, den das Skript mitbringt. Unter Linux prüft sie die OpenPGP-Signatur (.asc) mit sqv oder gpgv. Unter macOS prüft sie die einfache RSA-Signatur desselben Schlüssels (.sig) mit dem /usr/bin/openssl des Systems, sodass vorher nichts installiert werden muss.
4. Sie installiert die Binärdatei als /usr/local/bin/ironflock, anstelle einer vorhandenen. Die neue Datei wird neben die alte kopiert und durch Umbenennen an ihre Stelle gesetzt, sodass ein ironflock, das in diesem Moment läuft, die Binärdatei behält, mit der es gestartet ist. Auf einem Mac ohne /usr/local/bin legt das Skript den Ordner an.
5. Sie führt ironflock mit den Argumenten aus, die nach bash -s -- folgen. Ohne Argumente installiert sie nur und nennt den nächsten Schritt.

Auf einer Linux-Maschine mit amd64-CPU sieht die Ausgabe so aus:

Download base: https://instance-registry.ironflock.com/dl
Downloading ironflock 2.0.2 (linux/amd64)...
Signature verified (key F6C94D96CE315377ACA7C8EA4990543373212788).
Installed ironflock 2.0.2 as /usr/local/bin/ironflock.

Connect this machine to IronFlock with:
  sudo ironflock agent install -c /path/to/device.flock
All commands: ironflock --help
Tab completion in your shell: ironflock completion --help

Auf einem Mac nennt sie als nächsten Schritt ironflock os flash, das IronFlockOS für ein Gerät auf einen USB-Stick oder eine SD-Karte schreibt. Ersetzt sie ein vorhandenes ironflock, endet die Zeile Installed mit , in place of the one that was there.

Voraussetzungen

• Root-Rechte — das Skript schreibt nach /usr/local/bin. Führen Sie es mit sudo bash aus.
• curl oder wget — für die Downloads.
• Unter Linux base64 und sqv oder gpgv — für die Signaturprüfung. apt hängt von sqv oder gpgv ab, daher hat jedes Debian und Ubuntu eines davon. Fehlen beide, bricht das Skript ab und nennt apt install gpgv.
• Unter macOS nichts, was nicht zum System gehört.

Eine POSIX-Shell führt das Skript aus: bash, sh, dash oder BusyBox ash.

Eine fehlende oder falsche Signatur

Eine fehlende oder falsche Signatur stoppt das Skript, bevor es irgendetwas installiert, und ein zuvor installiertes ironflock bleibt, wie es war. Das Skript endet mit Exit-Code 1 und einer Zeile auf stderr, zum Beispiel:

install.sh: https://instance-registry.ironflock.com/dl/cli/linux/amd64/2.0.2/ironflock is not signed by IronFlock: not installing it

Ein fehlgeschlagener Download stoppt das Skript genauso: Es wird nichts installiert.

Installieren und einen Befehl ausführen, in einer Zeile

Die Argumente nach bash -s -- gehen an ironflock, sobald es installiert ist. Diese Zeile installiert ironflock und verbindet die Maschine mit IronFlock als Gerät der Gerätekonfigurationsdatei (.flock) device.flock:

curl -fsSL https://instance-registry.ironflock.com/dl/cli/install.sh | sudo bash -s -- agent install -c device.flock

Bei curl ... | bash ist die Standardeingabe des Skripts das Skript selbst. Das Skript lässt ironflock deshalb von Ihrem Terminal lesen, sodass die Fragen des Befehls Sie trotzdem erreichen und Sie sie wie gewohnt beantworten. Ohne Terminal (ein cloud-init-Skript, CI) erhält ironflock keine Eingabe: Ein Befehl, der fragt, endet mit Exit-Code 4, wenn Sie nicht --yes hinzufügen. Das Skript endet mit dem Exit-Code von ironflock. ironflock agent install beschreibt den Befehl.

Aktualisieren

sudo ironflock self-update ersetzt ironflock durch das neueste Release, nach denselben Prüfungen gegen den Release-Schlüssel von IronFlock (ironflock self-update). ironflock version --check zeigt, welche Version Sie haben und ob ein neueres Release erschienen ist (ironflock version).

Auch die Installationszeile oben auf dieser Seite aktualisiert: Führen Sie sie erneut aus, und sie ersetzt /usr/local/bin/ironflock durch das aktuelle Release.

Auf einem IronFlockOS-Gerät kommt ironflock mit dem System, und ironflock os update aktualisiert es mit dem System.

Das Installationsskript vorher prüfen

Um install.sh selbst zu prüfen, bevor es als root läuft, laden Sie es mit seiner Signatur herunter, importieren den Release-Schlüssel und prüfen die Signatur mit gpg:

curl -fsSLO https://instance-registry.ironflock.com/dl/cli/install.sh
curl -fsSLO https://instance-registry.ironflock.com/dl/cli/install.sh.asc
curl -fsSL https://instance-registry.ironflock.com/dl/cli/ironflock-bootstrap.asc | gpg --import
gpg --verify install.sh.asc install.sh

gpg muss eine gültige Signatur des Schlüssels mit dem Fingerabdruck F6C9 4D96 CE31 5377 ACA7 C8EA 4990 5433 7321 2788 melden. Vergleichen Sie ihn mit dem IronFlock-Bootstrap-Schlüssel unter Signaturschlüssel. Führen Sie dann das geprüfte Skript aus, ohne Argumente oder mit den Argumenten für ironflock:

sudo bash install.sh
sudo bash install.sh agent install -c device.flock

Download-Basis

ironflock und das Installationsskript laden aus der IronFlock-Cloud herunter, von https://instance-registry.ironflock.com/dl. Eine andere Download-Basis, etwa einen Spiegel in Ihrem Netzwerk, geben Sie auf eine von zwei Arten an. Für ein Gerät einer IronFlock-Appliance finden einige Befehle den Download-Spiegel der Appliance von selbst:

Unterhalb der Download-Basis liest das Installationsskript cli/version.txt und cli/<system>/<arch>/<version>/ironflock, jeweils mit ihrer Signatur .asc und .sig. Es prüft sie gegen den Release-Schlüssel, den es mitbringt, unabhängig von der Download-Basis, sodass ein Spiegel die signierten Dateien von IronFlock unverändert ausliefert. ironflock liest den IronFlockOS-Katalog und die Images unterhalb von ironflockos/, den Geräte-Agenten unterhalb von device-agent/ und unterhalb von cli/ das neueste Release (version.txt, für self-update und version --check) und die ironflock-Binärdateien (für self-update und für --host die anderer Plattformen).

Standardmäßig gibt sudo die Variablen Ihrer Shell nicht weiter. Setzen Sie die Variable nach sudo, oder geben Sie das Flag an:

# ironflock von einem Spiegel installieren
curl -fsSL https://mirror.example.com/dl/cli/install.sh | sudo IRONFLOCK_DL_BASE=https://mirror.example.com/dl bash
 
# Diese Maschine mit dem Agenten vom Spiegel verbinden
sudo ironflock agent install -c device.flock --download-base https://mirror.example.com/dl

Zwei Befehle verwenden die Download-Basis anders. agent update lässt den Agenten von seinem eigenen Update-Server aktualisieren, der update_url seiner .flock-Datei, und die Download-Basis ändert daran nichts. os update nimmt das Flag, dann die Variable, dann die update_url der .flock-Datei des Agenten. Über --host geht die Download-Basis mit auf die andere Maschine; eine mit Anmeldedaten darin (https://user:[email protected]/dl) endet mit Exit-Code 2, bevor irgendeine Maschine erreicht wird.

Geräte einer IronFlock-Appliance

Die .flock-Datei, die eine IronFlock-Appliance ausstellt, nennt den Download-Spiegel der Appliance als Update-Server des Agenten (update_url), zum Beispiel http://10.0.0.5:15002/dl, oder https://registry.<domain>/dl, wenn die Appliance mit einer Domain läuft. Ist weder --download-base noch IRONFLOCK_DL_BASE gesetzt, nehmen agent install, doctor und os install ihre Dateien von diesem Spiegel, sodass sich eine Maschine, die die Appliance erreicht, aber nicht ironflock.com, verbinden oder umstellen lässt. Eine .flock-Datei der IronFlock-Cloud nennt einen Host der Cloud und nimmt die Cloud.

• Was der Spiegel nicht liefert, kommt vom selben Pfad unterhalb der Download-Basis der IronFlock-Cloud, mit einer Warnung: bei agent install eine Zeile Warning: auf stderr und ein Eintrag in warnings im --json-Ergebnis, bei os install eine Warnung im Plan, bei doctor eine warning der Prüfung download_tree. agent install und os install scheitern nur, wenn weder der Spiegel noch die Cloud eine Datei liefert, und ihr Fehler nennt dann beide.
• agent install und os install erreichen den Spiegel direkt und die Cloud über den Proxy, wenn es einen gibt.
• Ein HTTPS-Spiegel mit einem Zertifikat der eigenen CA der Appliance funktioniert nur, wo das System der Maschine dieser CA vertraut.

Einige Downloads kommen weiterhin von anderswo:

• install.sh und die ironflock-Binärdatei kommen von ironflock.com. Mit --host geht die Binärdatei von Ihrem Computer auf die Maschine (Entfernte Maschinen über SSH).
• agent install nimmt die Pakete der Distribution und Docker von deren eigenen Servern.
• self-update und version --check lesen das Flag, dann die Variable, sonst die IronFlock-Cloud, nicht den Spiegel der Appliance.

Nach der Installation bezieht der Agent seine Updates von der Appliance. Siehe Edge-Geräte.

Tab-Vervollständigung

ironflock completion gibt das Skript aus, mit dem Ihre Shell ironflock-Befehlszeilen vervollständigt, wenn Sie Tab drücken.

ironflock completion <shell>

Die Shell ist bash, zsh oder fish. Läuft unter Linux und macOS. Braucht keine Root-Rechte. Fragt nichts. Der Befehl hat keine eigenen Flags; es gelten die globalen Flags.

Führen Sie die Zeile für Ihre Shell aus, um in der Shell zu vervollständigen, in der Sie gerade tippen. Fügen Sie die Zeile der Datei in der dritten Spalte hinzu, um in jeder neuen Shell zu vervollständigen:

Das Skript vervollständigt:

• die Befehle und ihre Flags;
• die Werte der Flags, die nur wenige Werte kennen: --channel, --variant und --kernel von os images, --channel von os update sowie --installer-confirm, --installer-after und --installer-allow-usb von os flash;
• eine .flock-Datei für -c;
• die Dateinamen der Shell für --hosts, --proxy-password-file, --wifi-password-file, --image-file, --output, --drive und --disk.

Andere Flags und die Argumente anderer Befehle vervollständigen nichts. Zum Vervollständigen fragt das Skript ironflock nach den passenden Wörtern, und ironflock antwortet aus seiner eigenen Liste der Befehle: Das Vervollständigen führt keinen Befehl aus, listet kein Laufwerk auf, lädt nichts herunter und erreicht keine andere Maschine, auch wenn die Zeile --host enthält. Mit --host oder --hosts wird ironflock completion auf dieser Maschine beantwortet, wie --help auch.

# In der bash vervollständigen, in der Sie gerade tippen
eval "$(ironflock completion bash)"
 
# In jeder neuen bash vervollständigen
echo 'eval "$(ironflock completion bash)"' >> ~/.bashrc

$ eval "$(ironflock completion bash)"
$ ironflock os images --kernel <Tab>
rt   std

Mit --json ist das Ergebnis das Skript in einem JSON-Objekt:

{"shell":"bash","script":"..."}

Eine fehlende oder unbekannte Shell oder mehr als eine ist eine falsche Befehlszeile: Exit-Code 2, und die Fehlermeldung nennt die Shells, die der Befehl akzeptiert.

ironflock version

Gibt die Version der ironflock-Binärdatei und die Plattform aus, für die sie gebaut wurde. Mit --check fragt es außerdem den Download-Server, ob ein neueres Release erschienen ist.

ironflock version [flags]

Läuft unter Linux und macOS. Braucht keine Root-Rechte. Fragt nichts. Es gelten die globalen Flags.

# Die Version von ironflock auf dieser Maschine
ironflock version
 
# Dasselbe als JSON
ironflock version --json
 
# Die Binärdatei, die über SSH auf einer anderen Maschine läuft: dieselbe Version, die Plattform dieser Maschine
ironflock --host pi@device-17 version
 
# Ist ein neueres Release erschienen?
ironflock version --check

ironflock 2.0.2 linux/amd64

{"version":"2.0.2","os":"linux","arch":"amd64"}

Über --host ist die Plattform die der anderen Maschine, zum Beispiel ironflock 2.0.2 linux/arm64: Die andere Maschine führt eine Binärdatei derselben Version für ihre eigene Plattform aus.

Ein Entwicklungs-Build nennt seinen Commit: 2.0.0-23-g5b38681 ist der Build von Commit 5b38681, 23 Commits nach Release 2.0.0.

Ist ein neueres Release erschienen?

--check liest cli/version.txt der Download-Basis (--download-base, sonst IRONFLOCK_DL_BASE, sonst die IronFlock-Cloud) und prüft die Datei gegen ihre Signatur (.asc) mit dem Release-Schlüssel von IronFlock, den die Binärdatei mitbringt. Es fragt über den Proxy, den agent configure eingestellt hat (/etc/ironflock/proxy.env), sonst über den Proxy der Umgebung. Nur root liest diese Datei, daher nimmt es ohne Root-Rechte den der Umgebung. version --check und self-update sind die einzigen Befehle, die nach dem neuesten Release fragen; kein Befehl tut das von selbst.

Eine zweite Zeile auf stdout sagt, was es gefunden hat und was ein neueres Release installiert: self-update, unter IronFlockOS os update.

$ ironflock version --check
ironflock 2.0.3 linux/amd64
ironflock 2.1.0 is out at https://instance-registry.ironflock.com/dl. 'sudo ironflock self-update' installs it.

Nennt version.txt die Version dieser Binärdatei, lautet die zweite Zeile This is the newest release. Ist diese Binärdatei neuer, ein Entwicklungs-Build nach dem Release, sagt die Zeile das. Ein Entwicklungs-Build x.y.z-N-g<commit> gilt als neuer als Release x.y.z und älter als das nächste; mit N = 0 steht er mit x.y.z gleich, und die Zeile sagt, dass kein neueres Release erschienen ist.

Mit --json hat das Objekt zwei Felder mehr: latest_version, was version.txt nennt, und newer, ob das neuer ist als diese Binärdatei.

{"version":"2.0.3","os":"linux","arch":"amd64","latest_version":"2.1.0","newer":true}

Der Exit-Code ist 0, ob ein neueres Release erschienen ist oder nicht. Er ist 1, wenn der Server nicht antwortet, keine version.txt hat oder eine, die nicht mit dem Schlüssel signiert ist. Über --host nennt die erste Zeile die Binärdatei dieses Builds, wie bei version, und die andere Maschine fragt den Server.

ironflock self-update

Ersetzt die laufende ironflock-Binärdatei durch das neueste Release oder durch das Release, das --version nennt, auch ein älteres. Das Release wird gegen den Release-Schlüssel von IronFlock geprüft, bevor sich auf der Festplatte irgendetwas ändert.

ironflock self-update [flags]

Läuft unter: Linux und macOS; nicht unter IronFlockOS. Root-Rechte: nötig für /usr/local/bin/ironflock (Wer die Binärdatei ersetzen darf). Fragt: ja, nachdem es gesagt hat, welches Release welches ersetzt; --yes antwortet.

# ironflock auf das neueste Release aktualisieren; der Befehl fragt vorher
sudo ironflock self-update
 
# Ohne Frage aktualisieren und das Ergebnis als JSON lesen
sudo ironflock self-update --yes --json
 
# Zu einem älteren Release zurückkehren
sudo ironflock self-update --version 2.0.3
 
# Das auf einer anderen Maschine installierte ironflock aktualisieren
ironflock --host pi@device-17 self-update --yes

Was es ersetzt, und womit

• Die Datei. Die laufende Binärdatei, mit allen symbolischen Links aufgelöst: Die Datei, auf die ein Link zeigt, wird ersetzt, und der Link bleibt. Der Befehl nennt die Datei vor allem anderen. Der Ordner /opt/ironflock/device-init einer Agent-Installation enthält die Aufzeichnung dieser Installation, kein ironflock, und der Befehl rührt ihn nicht an.
• Das Release. Ohne --version das neueste: was cli/version.txt der Download-Basis nennt (--download-base, sonst IRONFLOCK_DL_BASE, sonst die IronFlock-Cloud), die Datei, die auch die Installationszeile liest. Die Binärdatei eines Release ist cli/<system>/<arch>/<version>/ironflock. Es gibt keine Kanäle: Ein anderer Download-Baum ist eine andere Download-Basis, etwa ein Spiegel.
• Der Proxy. Die Downloads gehen über den Proxy, den agent configure eingestellt hat (/etc/ironflock/proxy.env), sonst über HTTP_PROXY, HTTPS_PROXY und NO_PROXY der Umgebung. sudo und ein Befehl über --host haben keinen Proxy in ihrer Umgebung. Die Datei gehört root, daher nimmt ein Lauf ohne Root-Rechte den Proxy der Umgebung und sagt das. Der Befehl sagt, wenn er den der Datei nimmt.
• Nichts zu tun. Ist die Binärdatei bereits dieses Release oder neuer (ein Entwicklungs-Build danach), sagt der Befehl das und endet mit Exit-Code 0, ohne Frage und ohne Download; das outcome des Ergebnisses ist current. Ohne --version kehrt er nie zu einem älteren Release zurück.

Die Prüfungen

Bevor die Binärdatei ersetzt wird:

1. version.txt wird gegen ihre Signatur mit dem Release-Schlüssel von IronFlock geprüft, den die laufende Binärdatei mitbringt.
2. Die neue Binärdatei wird gegen ihre Signatur mit demselben Schlüssel geprüft und gegen ihre Build-Informationen: das Programm ironflock, für diese Plattform, aus einem unveränderten Quellbaum.
3. Sie wird neben die alte geschrieben, in denselben Ordner, mit Modus, Eigentümer und Gruppe der alten, und einmal ausgeführt (version --json). Sie muss sagen, dass sie das verlangte Release ist, auf dieser Plattform. Eine Signatur bindet keine Version, daher wird hier eine ältere signierte Binärdatei abgelehnt, die anstelle der neuesten ausgeliefert wird.
4. Erst dann wird sie in einem Schritt über die alte umbenannt.

Es braucht kein sqv oder gpgv: ironflock prüft die Signaturen selbst.

Eine Datei, die eine Prüfung nicht besteht, ersetzt die Binärdatei nie, und die neue Datei daneben wird wieder entfernt. Ein Lauf, der scheitert, abgelehnt oder unterbrochen wird, lässt die alte Binärdatei, wie sie war. Ein ironflock-Befehl, der läuft, während die Datei ersetzt wird, macht mit der Datei weiter, mit der er gestartet ist. Ein zweites Strg+C oder ein Stromausfall zwischen dem Schreiben und dem Umbenennen kann die neue Datei (.ironflock.new-* neben der Binärdatei) zurücklassen; entfernen Sie sie von Hand.

Wer die Binärdatei ersetzen darf

Der Befehl braucht Schreibrechte im Ordner der Binärdatei und muss als Eigentümer der Binärdatei und Mitglied ihrer Gruppe laufen oder als root, damit die neue Datei Eigentümer und Gruppe behält. Für /usr/local/bin/ironflock, wohin die Installationszeile sie legt, heißt das root. Sonst endet der Befehl mit Exit-Code 3, bevor etwas heruntergeladen wird, nennt den Eigentümer oder die Gruppe und nennt die Befehlszeile mit sudo.

IronFlockOS und andere Maschinen

• IronFlockOS bringt ironflock mit seinem System mit, und jedes OS-Update ersetzt das System als Ganzes. Dort endet der Befehl mit Exit-Code 3, bevor er sich irgendetwas ansieht, und nennt os update. Auf dem IronFlockOS-Installer-Stick lehnt er ab wie die agent-Befehle.
• Über --host ist die laufende Binärdatei die Kopie des Laufs, die entfernt wird, wenn der Befehl endet. Der Befehl aktualisiert deshalb stattdessen /usr/local/bin/ironflock der Maschine. Fehlt diese Datei, endet er mit Exit-Code 3 und nennt die Installationszeile. Ein installiertes ironflock, das nicht läuft oder seine Version nicht nennt, beendet ihn ebenfalls mit Exit-Code 3, bevor etwas heruntergeladen wird: Die Installationszeile installiert ironflock neu.
• Auf mehreren Maschinen (--host mehrfach, --hosts) aktualisiert mit --yes jede Maschine ihr /usr/local/bin/ironflock.

Ergebnis

$ sudo ironflock self-update
This ironflock is 2.0.3, at /usr/local/bin/ironflock.
Download base: https://instance-registry.ironflock.com/dl (from default)
The downloads go through the proxy of the install's record (/etc/ironflock/proxy.env).
The newest release at https://instance-registry.ironflock.com/dl is ironflock 2.1.0 (its version.txt is signed by key F6C94D96CE315377ACA7C8EA4990543373212788).
ironflock 2.1.0 replaces 2.0.3 at /usr/local/bin/ironflock.
A command of ironflock that runs now goes on with 2.0.3; the next one runs 2.1.0.
? Install ironflock 2.1.0? Yes
Downloading ironflock 2.1.0 for linux/amd64 from https://instance-registry.ironflock.com/dl.
Signature verified (key F6C94D96CE315377ACA7C8EA4990543373212788): the program ironflock for linux/amd64.
The new file says it is ironflock 2.1.0 linux/amd64; it is in place.
ironflock at /usr/local/bin/ironflock is updated from 2.0.3 to 2.1.0.

Die Binärdatei wird nach der Antwort heruntergeladen. Ohne Terminal oder mit --json braucht der Befehl --yes. Mit --json, für eine Binärdatei, die bereits das neueste Release ist:

{"outcome":"current","path":"/usr/local/bin/ironflock","version":"2.1.0","latest_version":"2.1.0"}

Exit-Codes