Befehle für den Geräte-Agenten

Die Befehle ironflock agent verbinden eine Linux-Maschine als Gerät mit IronFlock und kümmern sich von da an um den Geräte-Agenten. Mit ihnen installieren Sie den Agenten, geben ihm eine andere Gerätekonfiguration oder einen anderen Proxy, aktualisieren, stoppen und starten ihn, lesen sein Log und entfernen ihn wieder.

Der Geräte-Agent

Der Geräte-Agent ist das Programm, das eine Maschine als Gerät mit IronFlock verbindet und die Apps des Projekts des Geräts in Docker ausführt. Welches Gerät eine Maschine wird, legt die Gerätekonfigurationsdatei (.flock) fest, die IronFlock Studio für jedes Gerät ausgibt (Geräte verbinden).

Jeder Agent-Befehl braucht Root-Rechte und läuft unter Linux. Ohne Root-Rechte endet er mit Exit-Code 3 und ruft sudo nicht selbst auf (Root-Rechte). Unter macOS enden die Agent-Befehle mit Exit-Code 3, bevor sie sich irgendetwas ansehen; führen Sie sie auf der Linux-Maschine aus oder vom Mac aus mit --host. Auf einem IronFlockOS-Gerät bringt das Image den Agenten mit seinem System mit: agent install und agent remove lehnen dort ab, und agent configure -c registriert das Gerät mit einer anderen .flock.

Jeder Befehl akzeptiert außerdem die globalen Flags --yes, --json, --download-base, --host, --hosts und --parallel (Globale Flags). Eine Frage braucht ein Terminal; ohne Terminal geben Sie --yes an (Fragen und Bestätigung).

Mit --host läuft ein Befehl über SSH auf einer anderen Maschine (Entfernte Maschinen über SSH). Auf mehreren Maschinen gleichzeitig (--host mehrfach angegeben oder --hosts) laufen agent restart, agent start und agent logs unverändert, agent logs --follow aber nicht mit --json. agent stop, agent update, agent configure und agent remove brauchen dort --yes, da niemand gefragt wird, und agent configure nimmt kein -c an, da eine .flock ein einzelnes Gerät nennt. agent install läuft jeweils nur auf einer Maschine.

So sieht ein installierter Agent aus

Der Agent schreibt außerdem bei jedem Start selbst einige Einstellungen des Hosts: den Slice ironflock.slice, in dem er läuft und der Arbeitsspeicher für ihn freihält, den systemd-Watchdog, die Absturzeinstellungen des Kernels und eine Obergrenze für die Größe des Journals.

Auf einer Maschine, die ein früherer IronFlock-Installer eingerichtet hat, kann der Agent noch im alten Layout /opt/reagent liegen (Dienst reagent.service, Log /var/log/reagent.log), das der Agent selbst nach /opt/ironflock/device-agent verschiebt. ironflock status zeigt, welches Layout eine Maschine hat, und die Ablehnungen unten nennen die Fälle, in denen es darauf ankommt.

ironflock agent install

Installiert den Geräte-Agenten in /opt/ironflock/device-agent, Docker, wenn es fehlt, und die Host-Voreinstellungen eines Geräts und verbindet die Maschine als Gerät der .flock mit IronFlock. Der Agent startet sofort und aktualisiert sich von da an selbst.

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

Läuft unter: Linux auf Basis von Debian oder Ubuntu, mit systemd; nicht unter IronFlockOS. Root-Rechte: nötig. Fragt: bevor er die Pakete und Docker installiert, und für jede Host-Voreinstellung; --yes beantwortet jede Frage mit ihrem Standard.

Die Maschine braucht Internetzugang, den Download-Server, den --download-base angibt (Download-Basis), oder den Download-Spiegel der Appliance, die die .flock nennt (Woher der Agent kommt). Die Hosts, die ein Gerät erreichen muss, sind unter Netzwerkanforderungen aufgeführt.

Woher der Agent kommt

Der Agent besteht aus seiner Kanalzuordnung, seiner Binärdatei und deren .sha256 und .sig. Der Befehl nimmt sie:

1. von --download-base, sonst von IRONFLOCK_DL_BASE: nur von diesem Server.
2. Sonst vom Download-Spiegel der IronFlock-Appliance, die die .flock als ihren Update-Server nennt (update_url), wenn dessen Host keiner der IronFlock-Cloud ist. So wird eine Maschine installiert, die die Appliance erreicht, aber nicht ironflock.com. Eine .flock der IronFlock-Cloud nimmt die Cloud.
3. Sonst aus der IronFlock-Cloud, https://instance-registry.ironflock.com/dl.

Der Befehl nennt die Basis auf stderr: Download base: ... (from the device's .flock), sonst (from --download-base), (from IRONFLOCK_DL_BASE) oder (from default).

Mit dem Spiegel der Appliance kommen die Dateien zuerst vom Spiegel und, wo der Spiegel sie nicht liefert, vom selben Pfad unterhalb der Download-Basis der IronFlock-Cloud:

• Die Kanalzuordnung — liefert der Spiegel gerade keine (keine Antwort, keine vorhanden, ein Fehlerstatus), kommt alles aus der Cloud, und die Version ist die, die die Zuordnung der Cloud nennt. Eine Zuordnung, die der Spiegel liefert und die abgelehnt wird (ihre Signatur, keine Version), lässt die Installation scheitern, wie bei jedem Server.
• Die Binärdatei, ihre .sha256 und ihre .sig — jede, die der Spiegel nicht liefert, kommt aus der Cloud. Bestehen die Dateien des Spiegels die Prüfungen nicht (Prüfsumme, Signatur), kommen alle drei aus der Cloud.

Jeder Rückgriff ist eine Zeile Warning: ... auf stderr, mit dem Spiegel, der Datei und dem Grund, und mit --json ein Eintrag in warnings im Ergebnis. Liefern weder der Spiegel noch die Cloud eine Datei, scheitert die Installation mit einem Fehler, der beide Quellen und beide Gründe nennt (neither the appliance's mirror ... nor the IronFlock cloud gives ...).

Der Spiegel ist der Update-Server der .flock, der den Proxy umgeht (Proxy). Ein HTTPS-Spiegel mit einem Zertifikat der eigenen CA der Appliance funktioniert nur, wo das System der Maschine dieser CA vertraut. Die Pakete der Distribution und Docker kommen weiterhin von ihren eigenen Servern, und install.sh und ironflock von ironflock.com; mit --host geht ironflock von Ihrem Computer auf die Maschine.

Prüfungen vor der Installation

Bevor er irgendetwas ändert, führt der Befehl die Prüfungen von ironflock doctor aus, die zeigen, ob er gelingen kann: system, systemd, disk_space, clock, dns, proxy, download_tree, device_endpoint, docker_registry und update_server. Sie laufen für die .flock von -c, mit der Download-Basis und den Proxy-Flags der Installation.

Vier davon halten die Installation an, wenn sie fehlschlagen, da die Installation dann mit Sicherheit oder auf halbem Weg scheitern würde:

Die Meldung nennt die Prüfung, ihren Befund und ihren Hinweis. Jeder andere Befund ist eine Warnung auf stderr, und die Installation geht weiter: Der Agent verbindet sich, aktualisiert sich und lädt seine Apps, sobald das Netzwerk es zulässt. Ein Ergebnis warning oder skipped hält die Installation nie an. Führen Sie ironflock doctor -c device.flock aus, um vor der Installation jede Prüfung zu sehen.

Schritte

1. Nennt die Pakete, die er installiert, und fragt. Installiert sie mit apt.
2. Installiert Docker, wenn die Maschine keines hat, und fragt vorher.
3. Lädt den Agenten des Produktionskanals herunter und prüft ihn gegen seine Prüfsumme und seine Signatur. Eine Installation, die keinen geprüften Agenten bekommt, hält hier an, vor allen folgenden Schritten.
4. Konfiguriert Docker: den Proxy, wenn einer angegeben ist, und bei einem Docker, das diese Installation mitgebracht hat oder das noch nichts enthält, das data-root im Ordner des Agenten. Ein Docker, das Images oder Container enthält, behält seine Konfiguration und seine Daten.
5. Richtet die Host-Voreinstellungen ein (Tabelle unten). Jede ist am Terminal eine Auswahl; --yes nimmt den Standard.
6. Installiert den Agenten in /opt/ironflock/device-agent und startet ihn.

Die Installation fügt außerdem ein Login-Banner hinzu. Alles, was die Installation ändert, wird in /opt/ironflock/device-init/installed.json geschrieben. Schlägt ein Schritt ab Schritt 4 fehl, sagt der Fehler, dass der Versuch festgehalten ist und dass derselbe Befehl, erneut ausgeführt, ihn zuerst rückgängig macht. Findet der Befehl einen solchen früheren Versuch, macht er ihn rückgängig, sobald die Prüfungen bestanden sind: Er listet auf, was er rückgängig macht, fragt und installiert dann erneut.

Proxy

Die Proxy-Flags setzen den Unternehmens-Proxy für die Downloads der Installation, für Docker und für den Agenten. Jede Einstellung kommt aus ihrem Flag, sonst aus den Umgebungsvariablen HTTP_PROXY, HTTPS_PROXY und NO_PROXY (oder ihren kleingeschriebenen Formen).

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 ohne das Passwort, http://[email protected]:3128, und --proxy-password-file liefert das Passwort. Der Befehl setzt das Passwort in die URLs der Flags ein, die einen Benutzer nennen.

Warnung: Schreiben Sie das Proxy-Passwort nie in die URL. Befehlszeilen erscheinen in ps und im Shell-Verlauf, daher wird eine URL mit Passwort als falsche Befehlszeile abgelehnt, und der Fehler wiederholt sie nicht. Schreiben Sie das Passwort in eine Zeile einer Datei, oder leiten Sie es mit --proxy-password-file /dev/stdin über eine Pipe ein (Secrets).

Neben den Hosts von --no-proxy umgehen diese den Proxy (NO_PROXY): localhost, 127.0.0.1 und ::1 sowie der Download-Server und der Update-Server der .flock (ihre update_url), wenn sie keine Hosts der IronFlock-Cloud sind, etwa eine Appliance oder ein Spiegel im LAN. Die Hosts der IronFlock-Cloud (ironflock.com, ironflock.dev und die Hosts darunter sowie storage.googleapis.com) liegen im Internet und gehen über den Proxy.

Die Installation schreibt den Proxy von Docker und dem Agenten in /etc/ironflock/proxy.env, die nur root liest (Modus 0600), und Docker startet neu, um ihn zu verwenden. Die systemd-Drop-ins ironflock-proxy.conf von docker.service und von ironflock-device-agent.service nennen diese Datei und enthalten selbst keine Einstellung, sodass systemctl show jedem Benutzer den Namen der Datei verrät und nichts von ihrem Inhalt. Ein eigenes Docker-Drop-in des Hosts (docker.service.d/http-proxy.conf) bleibt; die Einstellungen von IronFlock haben Vorrang vor seinen Environment=-Zeilen, und eine Warnung nennt es. Eine daemon.json mit proxies behält diese, da Docker sie vor allen anderen nimmt.

Um die Einstellungen später zu ändern, verwenden Sie agent configure. Zum Proxy des ganzen Standorts siehe Hinter einem Unternehmens-Proxy.

Beispiele

# Den Agenten installieren; der Befehl fragt vor jedem Schritt
sudo ironflock agent install -c device.flock
# Ohne Fragen installieren und verhindern, dass das Gerät in den Ruhezustand geht
sudo ironflock agent install -c device.flock --yes --disable-suspend
# Hinter einem Proxy installieren, der keine Anmeldung verlangt
sudo ironflock agent install -c device.flock --https-proxy http://proxy.example.com:3128
# Hinter einem Proxy mit Anmeldung installieren; das Passwort kommt aus einer Datei
sudo ironflock agent install -c device.flock --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt

Ergebnis

$ sudo ironflock agent install -c device.flock --yes
Done: the IronFlock device agent runs (systemctl status ironflock-device-agent).
The device appears online in IronFlock within a minute.

{"action":"installed","device":"demo-device","agent_version":"1.6.9"}

warnings steht nur dann im Ergebnis, wenn eine Datei aus der IronFlock-Cloud statt vom Spiegel der Appliance kam: ein Eintrag für jede, wie ihn die Warning:-Zeilen nennen.

Wann der Befehl ablehnt

Eine falsche Befehlszeile endet mit Exit-Code 2, bevor irgendetwas läuft: eine Proxy-URL mit Passwort; eine Proxy-URL, die einen Benutzer nennt, ohne --proxy-password-file; --proxy-password-file ohne eine Proxy-URL, die einen Benutzer nennt; ein Wert, der keine Proxy-URL ist. Eine Proxy-Variable der Umgebung, die keine Proxy-URL ist, zählt ebenfalls; der Fehler nennt die Variable, nicht ihren Wert.

Der Befehl lehnt mit Exit-Code 3 ab und ändert nichts, wenn:

• er nicht als root läuft oder die Maschine kein Linux ist;
• die Maschine IronFlockOS ausführt, vor allem anderen, ob als root oder nicht. Das Image bringt den Agenten und ironflock mit seinem System mit, und jedes OS-Update ersetzt das System als Ganzes. Die Meldung sagt, dass sich das Gerät bei seinem nächsten Start mit einer .flock auf seiner IRONFLOCKOS-Partition registriert und dass agent configure -c es sofort registriert. Auf dem IronFlockOS-Installer-Stick sagt sie, dass der Stick kein Gerät ist;
• bereits ein Agent installiert ist, auch im alten Layout /opt/reagent. Die Meldung nennt agent configure und agent remove;
• der Agent die Maschine gerade vom alten Layout umstellt;
• eine frühere Installation angehalten hat, bevor der Agent eingerichtet war, dabei das data-root von Docker verschoben hatte und Docker seitdem Images oder Container enthält: Diesen Versuch rückgängig zu machen, würde sie löschen;
• eine der Prüfungen system, systemd, disk_space oder download_tree fehlschlägt. --yes ändert daran nichts.

Eine mit Nein beantwortete Frage oder eine Frage ohne Terminal und ohne --yes beendet den Befehl mit Exit-Code 4. Ein fehlgeschlagener Schritt beendet ihn mit Exit-Code 1.

ironflock agent configure

Ändert, was die Installation eingerichtet hat: die .flock des Geräts, den Unternehmens-Proxy von Docker und dem Agenten oder beides. Startet neu, was die Änderung übernehmen muss.

ironflock agent configure [-c <device.flock>] [flags]

Läuft unter: Linux mit installiertem Agenten; unter IronFlockOS nur mit -c. Root-Rechte: nötig. Fragt: bevor Docker für neue Proxy-Einstellungen neu startet; --yes antwortet.

Geben Sie -c, ein Proxy-Flag oder beides an. Ohne eines davon gibt es nichts zu ändern: eine falsche Befehlszeile (Exit-Code 2).

Eine andere .flock

Mit -c erhält der Agent die angegebene .flock und startet neu: Die Maschine wird zum Gerät dieser .flock. Apps und ihre Daten bleiben. Hat die Installation einen SSH-Benutzer eingerichtet, folgt der SSH-Benutzer der .flock:

• Derselbe Projekteigentümer, ein anderer Geräteschlüssel — der alte Schlüssel wird nicht mehr akzeptiert, der neue schon.
• Ein anderer Projekteigentümer — der neue Eigentümer erhält seinen SSH-Benutzer, und der SSH-Benutzer des bisherigen Eigentümers verschwindet so, wie agent remove ihn entfernt: die sudo-Regel, der Schlüssel und das Konto mit seinem Home-Verzeichnis, wenn die Installation es angelegt hat.
• Eine .flock ohne Geräteschlüssel — der SSH-Benutzer verschwindet, und es kommt keiner hinzu.

Wechselt das Gerät den Eigentümer, kann der bisherige Eigentümer derjenige sein, der den Befehl ausführt, über SSH mit genau dem Konto, das verschwindet, und das Entfernen eines Kontos beendet seine Sitzungen. Daher arbeitet der Befehl in dieser Reihenfolge: Er richtet das Konto des neuen Eigentümers ein (Benutzer, Schlüssel, sudo-Regel), startet den Agenten mit der neuen .flock neu und nimmt erst dann dem bisherigen Eigentümer die sudo-Regel, die Sitzungen und das Konto (bei demselben Eigentümer nur den alten Schlüssel). Das Gerät hat einen neuen Zugang und ist online, bevor der alte Zugang verschwindet. Bevor die Sitzungen enden, sagt eine Zeile auf stderr das, zum Beispiel Removing the account anna, ...: a session of anna ends here.

• Startet der Agent mit der neuen .flock nicht neu, behält der bisherige Eigentümer den Zugang: Irgendjemand muss hineinkommen können.
• Ist nur der SSH-Benutzer des neuen Eigentümers fehlgeschlagen, verschwindet der Zugang des bisherigen Eigentümers trotzdem: Das Gerät hat den Eigentümer gewechselt und ist online.
• Wessen Zugang noch entfernt werden muss, ist in /opt/ironflock/device-init/installed.json festgehalten (users_to_remove). Jedes spätere agent configure -c und agent remove versucht es erneut.
• Ein Konto, das die neue .flock wieder einrichtet, wird nie entfernt (Eigentümer A, dann B, dann wieder A).
• Ab seiner ersten Änderung hält ein verlorenes Terminal oder eine verlorene SSH-Sitzung den Befehl nicht mehr an.

Über --host wird die Kopie der .flock auf der Maschine entfernt, sobald der Befehl sie gelesen hat. Ist der SSH-Benutzer von --host ein Konto, das verschwindet, endet die SSH-Sitzung mit dem Konto: Ihr Lauf endet dann mit Exit-Code 255 wie nach einer verlorenen Verbindung, und der Befehl auf der Maschine läuft bis zu seinem Ende weiter. Der Ordner des Laufs ironflock.XXXXXXXXXX mit seiner Binärdatei bleibt dann auf der Maschine zurück; in einem temporären Ordner bleibt er, bis dieser aufgeräumt wird, im Home-Verzeichnis des Kontos verschwindet er mit dem Konto.

Unter IronFlockOS

Mit -c registriert der Befehl das Gerät so, wie IronFlockOS es beim ersten Boot jedes neuen Root-Slots registriert, auf einem Gerät, das sich schon registriert hat, wie auf einem, das es noch nicht getan hat. Die angegebene .flock wird zur Kopie des Agenten, /opt/ironflock/device-agent/device-config.flock auf /data, und das Gerät wird in dieser Reihenfolge daraus eingerichtet: der SSH-Benutzer des Projekteigentümers, das WLAN, der Hostname aus dem Gerätenamen (außer /etc/ironflockos/enroll.conf sagt hostname-from-flock=no), der Agent, mit der neuen .flock neu gestartet, und dann das Entfernen des Zugangs des bisherigen Eigentümers.

Das nächste OS-Update registriert seinen neuen Root-Slot aus derselben Kopie. Die Datei, die Sie angegeben haben, bleibt, wo sie ist. Ein fehlgeschlagener Schritt hält den Agenten nicht davon ab, mit der neuen .flock neu zu starten, aber der Zugang des bisherigen Eigentümers verschwindet erst, wenn der Agent neu gestartet ist. Der Befehl endet dann mit Exit-Code 1 und nennt jeden fehlgeschlagenen Schritt; führen Sie denselben Befehl erneut aus, um sie zu wiederholen.

Die Proxy-Flags werden unter IronFlockOS abgelehnt. IronFlockOS hält den Proxy von Docker, dem Agenten und seiner Uhr in /etc/ironflockos/proxy.conf auf /data, und eine proxy.conf auf seiner IRONFLOCKOS-Partition ersetzt ihn beim nächsten Start.

Proxy-Einstellungen

• Jedes angegebene Proxy-Flag ersetzt seine Einstellung, und die anderen bleiben. --https-proxy allein ändert den HTTPS-Proxy und behält den HTTP-Proxy und die Hosts, die beide umgehen.
• Das Passwort von --proxy-password-file kommt in die angegebenen URLs, die einen Benutzer nennen. Ist keine URL angegeben, kommt es in die URLs der Einstellungen des Geräts, die einen nennen, sodass sich ein neues Passwort allein mit der Datei setzen lässt.
• --no-proxy und der erste Proxy eines Geräts, das keinen hatte, nehmen außerdem localhost, 127.0.0.1, ::1 und den Update-Server der .flock des Agenten auf, wenn er kein Host der IronFlock-Cloud ist (der einer Appliance).
• --remove-proxy entfernt die Einstellungen. Es nimmt kein anderes Proxy-Flag an.
• Die Proxy-Variablen Ihrer Umgebung ändern hier nichts: Nur die Flags zählen.

Die Liste der Hosts, die den Proxy umgehen, bleibt so, wie der Befehl sie vorfindet, außer --no-proxy gibt eine andere an. Nennt diese Liste einen Host der IronFlock-Cloud, nennt eine Warnung ihn, mit dem agent configure --no-proxy, das die Liste ohne ihn angibt. Ein Gerät, das das Internet nur über den Proxy erreicht, kann seinen Agenten nicht aktualisieren, solange der Download-Server der Cloud, instance-registry.ironflock.com, auf dieser Liste steht.

Die Einstellungen liegen in /etc/ironflock/proxy.env, die nur root liest, und die Drop-ins ironflock-proxy.conf von docker.service und ironflock-device-agent.service nennen diese Datei. Wenn sich die Einstellungen ändern, zeigt der Befehl sie vorher und nachher, ohne das Passwort. Dann starten Docker und der Agent neu. Ein Neustart von Docker stoppt die Apps des Geräts für einen Moment, daher sagt der Befehl das und fragt; --yes antwortet. Mit dem Passwort auf stdin gibt es kein Terminal, an dem gefragt werden kann: Geben Sie --yes an.

• Docker startet nicht neu, und nichts wird gefragt, wenn die daemon.json von Docker proxies setzt (Docker nimmt diese vor diesen Einstellungen) und wenn sich nichts ändert.
• Eine Unit, der nur ihr Drop-in fehlt, erhält es, und nur diese Unit startet neu.
• Ein eigenes Docker-Drop-in des Hosts bleibt, wie es ist. Ein anderes Drop-in des Agenten oder von Docker, das eine Proxy-Variable setzt, wird in einer Warnung genannt; die Einstellungen von IronFlock überschreiben es für jede Variable, die sie setzen. Ein Drop-in oder eine daemon.json mit einem Proxy-Passwort, das jeder Benutzer lesen kann, wird ebenfalls in einer Warnung genannt.
• Schlägt der Neustart von Docker fehl, startet der Agent trotzdem neu, und umgekehrt. Der Fehler (Exit-Code 1) nennt die Units, die noch mit den alten Einstellungen laufen, und das systemctl restart, das sie anwendet; ein zweiter Lauf findet die Einstellungen vor und startet nichts neu.
• Lassen sich die Einstellungen nicht schreiben, startet nichts neu, und der Fehler sagt, dass der Befehl erneut auszuführen ist.

Proxy-Einstellungen, die eine ältere Installation in Environment=-Zeilen von http-proxy.conf-Drop-ins geschrieben hat, wo jeder Benutzer sie mit systemctl show lesen kann, samt Passwort, ziehen bei jedem Lauf von agent configure nach /etc/ironflock/proxy.env um, auch bei einem nur mit -c. Keine Kopie der alten Dateien wird aufbewahrt. In der Regel behält der Umzug die Werte, sodass er nichts neu startet und nichts fragt; wo er den Proxy ändert, den eine Unit verwendet, sagt der Befehl, warum, zeigt den Proxy dieser Unit vorher und nachher und fragt. Ein Wert, den die Einstellungsdatei nicht aufnehmen kann (ein einfaches Anführungszeichen im Host oder in der Umgehungsliste, ein Steuerzeichen), zieht nicht um: Ein Lauf ohne Proxy-Flags lässt ihn, wo er ist, warnt und nennt das Flag, das den Wert neu angibt.

Beispiele

# Diese Maschine zum Gerät einer anderen .flock machen
sudo ironflock agent configure -c new-device.flock
# Einen HTTPS-Proxy mit Anmeldung setzen; das Passwort kommt aus einer Datei
sudo ironflock agent configure --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt
# Nur ein neues Proxy-Passwort setzen, von stdin gelesen, ohne Frage
sudo ironflock agent configure --proxy-password-file /dev/stdin --yes < proxy-password.txt
# Die Proxy-Einstellungen entfernen: Docker und der Agent verbinden sich direkt
sudo ironflock agent configure --remove-proxy

Ergebnis

$ sudo ironflock agent configure -c new-device.flock
Device configuration updated; the agent restarted.
$ sudo ironflock agent configure --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt
The proxy settings of Docker and the agent change:
  HTTP proxy:   none (unchanged)
  HTTPS proxy:  none -> http://[email protected]:3128 (with a password)
  No proxy for: localhost,127.0.0.1,::1
Docker restarts for the new settings: the apps of the device stop for a moment and start again.
? Continue? Yes
Proxy settings updated: HTTPS through http://[email protected]:3128 (with a password); not for localhost,127.0.0.1,::1.
Restarted: docker.service, ironflock-device-agent.service.

Unter IronFlockOS meldet -c die Registrierung:

Device configuration updated: this device enrolled as new-device, as IronFlockOS enrolls it at every new root slot; the agent restarted.

{"action":"configured","device":"new-device","restarted":["ironflock-device-agent.service"]}

{"action":"configured","proxy":{"password":false,"changed":true,"moved":false},"restarted":["docker.service","ironflock-device-agent.service"]}

Wann der Befehl ablehnt

Eine falsche Befehlszeile endet mit Exit-Code 2: nichts zu ändern; --remove-proxy mit einem anderen Proxy-Flag; eine Proxy-URL mit Passwort; eine Proxy-URL, die einen Benutzer nennt, ohne --proxy-password-file; --proxy-password-file mit URLs, von denen keine einen Benutzer nennt; ein Wert, der keine Proxy-URL und keine Liste von Hosts ist.

Der Befehl lehnt mit Exit-Code 3 ab und ändert nichts, wenn:

• kein Agent installiert ist (die Meldung nennt agent install), außer unter IronFlockOS, wo -c ein Gerät registriert, das sich noch nicht registriert hat;
• der Agent die Maschine gerade vom alten Layout umstellt;
• Proxy-Flags angegeben sind und der Agent noch im alten Layout /opt/reagent läuft. Sobald der Agent die Maschine umgestellt hat (ironflock status zeigt das Layout), funktioniert derselbe Befehl;
• Proxy-Flags unter IronFlockOS angegeben sind, mit oder ohne -c;
• --no-proxy oder --proxy-password-file allein auf einem Gerät ohne Proxy angegeben ist oder die Passwortdatei allein, wenn keine Proxy-URL des Geräts einen Benutzer nennt;
• Proxy-Flags einen Wert der alten Form behalten, den /etc/ironflock/proxy.env nicht aufnehmen kann; die Meldung nennt das Flag, das ihn neu angibt.

Unter IronFlockOS wird -c mit Exit-Code 3 abgelehnt, wenn die Registrierung die .flock nicht behalten würde:

• ein Zurücksetzen auf Werkseinstellungen angefordert ist und noch nicht begonnen hat (/boot/efi/factory-reset.conf, das os reset schreibt) oder bereits begonnen hat (/boot/efi/factory-reset.keep): Der nächste Start würde löschen, was der Befehl einrichtet;
• ein Zurücksetzen auf Werkseinstellungen offen ist oder aufgegeben wurde und die Dateien zurückhält, die mit ihm kamen (/run/ironflockos/factory-reset-hold; ironflock status sagt mehr);
• /data nicht eingehängt werden konnte, sodass die Kopie des Agenten im Root-Slot landen würde. Dann führt der Weg über eine .flock auf der IRONFLOCKOS-Partition;
• eine .flock auf der IRONFLOCKOS-Partition liegt; das Gerät registriert sich bei seinem nächsten Start damit, und die Meldung nennt sie;
• der Befehl auf dem IronFlockOS-Installer-Stick läuft, der kein Gerät ist;
• das System kein /usr/lib/ironflock/image.json hat oder einen Agenten im alten Layout.

ironflock agent update

Lässt den Agenten sich selbst auf das Release seines Kanals aktualisieren und verfolgt, was er tut. Der Agent sucht bei jedem Start nach einem neueren Release: Der Befehl startet ihn neu und meldet das Ergebnis. Das Gerät ist in IronFlock für einen Moment offline; seine Apps laufen weiter.

ironflock agent update [flags]

Läuft unter: Linux mit installiertem Agenten. Root-Rechte: nötig. Fragt: ja, nachdem er gesagt hat, was der Neustart bewirkt; --yes antwortet.

Der Befehl hat keine eigenen Flags und nimmt keine Version an. Der Agent folgt seinem Kanal (production oder test auf der Testplattform von IronFlock) und bezieht ihn von seinem Update-Server: der update_url seiner .flock (der Spiegel einer Appliance), sonst der IronFlock-Cloud. --download-base ändert daran nichts.

Was der Agent tut, in dieser Reihenfolge:

1. Er liest das Release seines Kanals. Ein Release, das auf diesem Gerät zweimal fehlgeschlagen ist, wird erst wieder heruntergeladen, wenn ein neueres erscheint.
2. Er lädt ein neueres Release in seinen Ordner herunter und prüft dessen Signatur.
3. Er setzt die neue Version ein und startet 10 Sekunden nach dem Download in sie neu. Er hält das Update zurück, wenn er zuletzt vor 12 Minuten bis einem Tag mit IronFlock verbunden war: Ein Update wird von einer Version aus aktiviert, von der bekannt ist, dass sie sich verbindet.
4. Die neue Version ist in der Bewährungsphase: Sie muss sich innerhalb von 10 Minuten nach ihrem Start mit IronFlock verbinden und 2 Minuten lang laufen. Tut sie das nicht oder stoppt sie vorher dreimal, kehrt der Agent zur vorherigen Version zurück.
5. Nach einem Rollback muss sich die vorherige Version verbinden. Dann lag der Fehler bei der neuen Version: Sie wird beim nächsten Update noch einmal versucht und nach ihrem zweiten Fehlschlag bis zu einem neueren Release gesperrt. Kann sich auch die vorherige Version nicht innerhalb von 10 Minuten verbinden, gibt der Agent dem Netzwerk die Schuld, und die neue Version wird beim nächsten Update erneut versucht.

Der Befehl verfolgt das in update-state.json im Ordner des Agenten und im Log des Agenten; aus der Zeit vor dem Neustart liest er aus beiden nichts. Sein Fortschritt geht als Textzeilen auf stderr, auch mit --json. Ein Download zeigt einmal pro Minute, wie viel er bisher hat.

Mit Exit-Code 1 wird das Ergebnis trotzdem geschrieben, und stderr erhält die Zeile Error:. Mit --json folgt kein Fehlerobjekt: stdout enthält das Ergebnis.

Beispiele

# Den Agenten aktualisieren; der Befehl fragt vor dem Neustart
sudo ironflock agent update
# Ohne Frage aktualisieren und das Ergebnis als JSON lesen
sudo ironflock agent update --yes --json

Ergebnis

$ sudo ironflock agent update --yes
The agent 1.6.9 restarts now and looks for a newer release on its channel: the device is offline in IronFlock for a moment, its apps keep running.
A newer release is downloaded and started. It has to connect to IronFlock within 10 minutes and stay up for 2, or the agent goes back to 1.6.9.
The agent restarted; it looks for a newer release.
Its channel offers 1.7.0: the agent downloads it.
Activating 1.7.0: the agent restarts into it.
1.7.0 runs on probation: it has to connect to IronFlock within 10 minutes and stay up for 2.
The agent was updated from 1.6.9 to 1.7.0: 1.7.0 connected to IronFlock and passed its probation.

Ein Agent, der aktuell ist, und einer, dessen neue Version zurückgerollt wurde:

{"outcome":"current","version":"1.7.0","channel_version":"1.7.0"}

{"outcome":"rolled_back","version":"1.6.9","channel_version":"1.7.0","failed_version":"1.7.0","reason":"did not connect within 10m0s","retry":"next_update"}

Wann der Befehl ablehnt

Der Befehl lehnt mit Exit-Code 3 ab, wenn kein Agent installiert ist (die Meldung nennt agent install), während der Agent die Maschine vom alten Layout umstellt, wenn der Agent im alten Layout läuft (seine Updates hinterlassen keinen Zustand, dem der Befehl folgen kann), und bei einem Agenten älter als 1.3.0, dem ersten, der sich unter seiner Unit selbst aktualisiert.

Er schlägt mit Exit-Code 1 und einem Fehler fehl, der sagt, wo nachzusehen ist, wenn der Neustart fehlschlägt und wenn das Update innerhalb der Fristen des Agenten nicht vorankommt: die Prüfung des Agenten innerhalb von 3 Minuten nach dem Neustart, der Download innerhalb von 30 Minuten, die Aktivierung innerhalb von 3 Minuten, jeder Start der neuen Version in der Bewährungsphase innerhalb von 12 Minuten, das Urteil des Agenten nach einem Rollback innerhalb von 12 Minuten und alles zusammen innerhalb von 84 Minuten. Der Agent macht von selbst weiter; ironflock status zeigt, wo er steht.

Strg+C beendet das Verfolgen, nicht das Update, und beendet den Befehl mit Exit-Code 130.

ironflock agent remove

Entfernt den Geräte-Agenten und macht rückgängig, was seine Installation festgehalten hat. Docker selbst und die Pakete bleiben installiert.

ironflock agent remove [flags]

Läuft unter: Linux mit installiertem Agenten; nicht unter IronFlockOS. Root-Rechte: nötig. Fragt: ja, nachdem er aufgelistet hat, was er entfernt. Bei der Frage ist „Nein“ vorausgewählt: Enter allein entfernt nichts.

Der Befehl hat keine eigenen Flags. Er entfernt:

• Den Agenten — den Agenten, seine Datenbank und /opt/ironflock/device-agent. Die Apps des Geräts und ihre Daten verschwinden mit, wenn Docker sie im Ordner des Agenten ablegt.
• Den SSH-Benutzer — das Konto nur, wenn die Installation es angelegt hat. Bei einem Konto, das schon vorher bestand, verschwindet nur der Geräteschlüssel aus seinen authorized_keys, die dem Benutzer bleiben. Der Zugang eines früheren Projekteigentümers, dessen Entfernen durch agent configure -c fehlgeschlagen war, verschwindet ebenfalls, aufgeführt mit „(a removal that had failed)“.
• Die Host-Voreinstellungen — das WLAN-Profil, das Login-Banner und die maskierten Sleep-Targets.
• Die Dateien, die die Installation geschrieben oder ersetzt hat — die Originale kommen zurück, mit ihrem Modus, ihrem Eigentümer und ihrer Gruppe.
• Die Proxy-Einstellungen — /etc/ironflock/proxy.env mit den Drop-ins, die sie nennen, und Proxy-Einstellungen, die eine ältere Installation in http-proxy.conf-Drop-ins hinterlassen hat. An ihre Stelle kommt nichts: Danach hat Docker keinen Proxy von IronFlock, und der Befehl hat das Proxy-Passwort nirgendwohin geschrieben. Hatte Docker einen Proxy von IronFlock, sagt das die Liste vor der Frage.
• Die Einstellungen, die der Agent selbst auf dem Host geschrieben hat — den Slice ironflock.slice mit dem Drop-in 10-ironflock-resources.conf seiner Unit, den systemd-Watchdog (/etc/systemd/system.conf.d/10-ironflock-watchdog.conf), die Absturzeinstellungen des Kernels (/etc/sysctl.d/60-ironflock-crash-recovery.conf, die der Kernel bis zum nächsten Boot behält) und die Obergrenze des Journals (/etc/systemd/journald.conf.d/10-ironflock.conf).
• Die Registry-Anmeldungen des Agenten — sobald der Agent gestoppt ist, führt der Befehl docker logout für die Registry aus, die die .flock nennt (docker_registry_url), und auf einem Gerät einer Appliance für registry.<appliance_domain>. Keine andere Anmeldung in /root/.docker/config.json wird angefasst. Ein fehlendes oder fehlschlagendes Docker hält das Entfernen nicht an; eine Zeile sagt, welche Anmeldung nicht entfernt wurde.

Ein eigenes Docker-Drop-in des Hosts bleibt, wie es ist. Ein Docker, das für das Entfernen nicht neu startet (seine Daten lagen nicht im Ordner des Agenten), verwendet bis zu seinem nächsten Neustart den Proxy, mit dem es gestartet ist.

Der Befehl listet auf stderr auf, was er entfernt, und fragt dann. Mit --json ist die Liste das Feld removed des Ergebnisses. Sobald der Befehl mit dem Entfernen begonnen hat, hält ihn ein verlorenes Terminal oder eine verlorene SSH-Sitzung nicht an: Der SSH-Benutzer, der verschwindet, nimmt seine Sitzungen mit, vielleicht die, in der der Befehl läuft, und das Entfernen läuft bis zu seinem Ende weiter.

Beispiele

# Den Agenten entfernen; der Befehl listet auf, was verschwindet, und fragt
sudo ironflock agent remove
# Den Agenten ohne Frage entfernen
sudo ironflock agent remove --yes

Ergebnis

$ sudo ironflock agent remove --yes
This removes:
  - the agent, its database and /opt/ironflock/device-agent (with Docker's images and containers)
  - the user operator and its home directory
  - /etc/profile.d/ironflock-motd.sh
The IronFlock device agent was removed from this machine.

{"action":"removed","removed":["the agent, its database and /opt/ironflock/device-agent (with Docker's images and containers)","the user operator and its home directory","/etc/profile.d/ironflock-motd.sh"]}

Wann der Befehl ablehnt

Der Befehl lehnt mit Exit-Code 3 ab, wenn kein Agent installiert ist und während der Agent die Maschine vom alten Layout umstellt. Unter IronFlockOS lehnt er vor allem anderen ab, ob als root oder nicht: Das Image bringt den Agenten mit seinem System mit, und jedes OS-Update und die nächste Registrierung würden ihn wieder einrichten. Die Meldung nennt ironflock os reset, das das Gerät auf ein frisch geschriebenes IronFlockOS ohne seine Identität bei IronFlock zurücksetzt. Auf dem IronFlockOS-Installer-Stick sagt sie, dass der Stick kein Gerät ist.

Die Antwort Nein oder eine Frage ohne Terminal und ohne --yes beendet den Befehl mit Exit-Code 4.

ironflock agent restart

Startet den Dienst des Agenten neu und prüft, dass der Agent wieder läuft: Seine Unit muss fünf Sekunden lang mit einem Prozess laufen. Das Gerät ist in IronFlock für diese Sekunden offline; die Apps laufen weiter.

ironflock agent restart [flags]

Läuft unter: Linux mit installiertem Agenten. Root-Rechte: nötig. Fragt: nichts.

Der Befehl hat keine eigenen Flags. Der Dienst ist ironflock-device-agent.service. In einem Terminal ausgeführt, das über den Agenten kommt (das Terminal des Geräts in IronFlock Studio oder SSH über IronFlock), beendet der Neustart diese Sitzung; das Gerät ist innerhalb einer Minute zurück.

# Den Agenten neu starten
sudo ironflock agent restart
# Ihn neu starten und den neuen Prozess als JSON lesen
sudo ironflock agent restart --json

$ sudo ironflock agent restart
The agent restarted: ironflock-device-agent.service runs, with process 4242.

{"action":"restarted","unit":"ironflock-device-agent.service","state":"running","main_pid":4242}

state ist der Zustand der Unit danach, benannt wie in ironflock status. main_pid ist der Prozess des Agenten, nach jedem Neustart ein neuer.

Lehnt ab mit Exit-Code 3, wenn kein Agent installiert ist (die Meldung nennt agent install -c <file>), während der Agent die Maschine vom alten Layout umstellt und wenn systemd die Unit des Agenten nicht kennt (die Meldung nennt agent remove).

Schlägt fehl mit Exit-Code 1, wenn der Agent nicht hochkommt: systemd kann die Unit nicht starten, oder ihr Prozess endet innerhalb der fünf Sekunden. Der Fehler nennt die Unit und wo ihre letzten Logzeilen stehen: das Log des Agenten (agent logs) und das Journal (journalctl -u <unit>).

ironflock agent stop

Stoppt den Dienst des Agenten. Das Gerät geht in IronFlock offline, und der Fernzugriff über IronFlock verschwindet mit dem Agenten: Eine Sitzung, die auf diesem Weg kam (das Terminal des Geräts in IronFlock Studio, SSH über IronFlock), endet, und IronFlock kann das Gerät nicht erreichen, bis der Agent wieder läuft. Die Apps laufen weiter, da Docker sie ausführt, nicht der Agent.

ironflock agent stop [flags]

Läuft unter: Linux mit installiertem Agenten. Root-Rechte: nötig. Fragt: ja, nachdem er gesagt hat, was das Stoppen des Agenten beendet; --yes antwortet.

Der Befehl hat keine eigenen Flags. agent start startet den Agenten wieder, ebenso der nächste Boot. Ein gestoppter Agent lässt sich nicht über IronFlock wieder starten. Ein Agent, der nicht läuft, hat nichts zu stoppen; dann fragt der Befehl nichts, und das Ergebnis hat kein action.

# Den Agenten stoppen; der Befehl sagt, was das beendet, und fragt
sudo ironflock agent stop
# Ihn ohne Frage stoppen
sudo ironflock agent stop --yes

$ sudo ironflock agent stop --yes
Stopping the agent (ironflock-device-agent.service) takes this device offline in IronFlock.
The remote access through IronFlock goes with it: a session that came that way (the device's terminal in Studio, SSH through IronFlock) ends.
The apps keep running. 'sudo ironflock agent start' starts the agent again, and so does the next boot.
The agent is stopped (ironflock-device-agent.service): the device is offline in IronFlock, and its apps keep running. 'sudo ironflock agent start' starts the agent again.

{"action":"stopped","unit":"ironflock-device-agent.service","state":"stopped"}

Lehnt ab mit Exit-Code 3 wie agent restart. Die Antwort Nein oder eine Frage ohne Terminal und ohne --yes beendet ihn mit Exit-Code 4.

ironflock agent start

Startet den Dienst des Agenten, wenn er nicht läuft, und prüft wie agent restart, dass der Agent hochkommt: Seine Unit muss fünf Sekunden lang mit einem Prozess laufen. Ein Agent, der bereits läuft, bleibt, wie er ist, und das Ergebnis hat dann kein action.

ironflock agent start [flags]

Läuft unter: Linux mit installiertem Agenten. Root-Rechte: nötig. Fragt: nichts. Der Befehl hat keine eigenen Flags.

# Den Agenten starten
sudo ironflock agent start
# Ihn starten und seinen Prozess als JSON lesen
sudo ironflock agent start --json

$ sudo ironflock agent start
The agent started: ironflock-device-agent.service runs, with process 4242. The device appears online in IronFlock within a minute.

Mit --json, bei einem Agenten, der bereits läuft:

{"unit":"ironflock-device-agent.service","state":"running","main_pid":4242}

Lehnt ab und schlägt fehl wie agent restart: Exit-Code 3, wenn kein Agent installiert ist, während der Agent die Maschine vom alten Layout umstellt und wenn systemd die Unit des Agenten nicht kennt; Exit-Code 1, wenn der Agent nicht hochkommt.

ironflock agent logs

Zeigt das Log des Agenten, /var/log/ironflock/device-agent.log, und die Dateien, in die der Agent es rotiert hat. Ändert nichts.

ironflock agent logs [flags]

Läuft unter: Linux mit installiertem Agenten; er liest die Dateien und braucht kein systemd. Root-Rechte: nötig, da der Agent sein Log nur für root schreibt (Modus 0600). Fragt: nichts.

Bei 100 MB benennt der Agent sein Log in device-agent-<time>.log im selben Ordner um und beginnt ein neues; er behält zwei. Der Befehl liest das Log und diese Dateien.

Der Agent schreibt ein JSON-Objekt pro Zeile: die Zeit des Eintrags (auf die Sekunde), sein Level, seine Meldung und weitere Felder. Die Textform zeigt einen Eintrag so, wie IronFlock Studio das Log des Agenten zeigt: die Zeit in UTC, das Level, die Meldung und ihren Fehler. Eine Zeile, die kein Eintrag ist, etwa der Stacktrace eines Absturzes, wird unverändert angezeigt. Steuerzeichen werden maskiert (\n, \x1b), sodass ein Eintrag am Terminal eine Zeile bleibt und das Terminal nicht steuern kann. Mit --json ist jede Zeile ein JSON-Objekt auf stdout: der Eintrag, wie der Agent ihn geschrieben hat, mit all seinen Feldern, oder {"message":...} für eine Zeile, die kein Eintrag ist.

• --since beginnt mit dem ersten Eintrag dieses Zeitpunkts oder später. Die Zeilen bleiben in der Reihenfolge, in der der Agent sie geschrieben hat. Eine Zeile ohne Zeit gehört zum Eintrag davor.
• Mit --follow wird eine Zeile angezeigt, sobald sie vollständig ist. Beginnt der Agent eine neue Datei, kommt zuerst der Rest der alten, dann die neue von ihrem Anfang an. Auf ein Log, das noch nicht existiert, wird gewartet. Strg+C beendet den Befehl mit Exit-Code 0; über --host beendet Strg+C den Lauf mit Exit-Code 130.
• Hat der Agent noch kein Log geschrieben, sagt stderr das, stdout bleibt leer, und der Exit-Code ist 0.

Beispiele

# Die letzten 100 Zeilen
sudo ironflock agent logs
# Alles aus der letzten Stunde
sudo ironflock agent logs --since 1h
# Die letzten 20 Zeilen, dann jede neue Zeile bis Strg+C
sudo ironflock agent logs --follow --lines 20
# Die letzten zehn Minuten als JSON, ein Objekt pro Zeile
sudo ironflock agent logs --since 10m --json

Ergebnis

$ sudo ironflock agent logs --lines 3
2026-11-10T11:58:02Z INFO connected to IronFlock
2026-11-10T11:58:03Z INFO 3 apps running
2026-11-10T11:59:40Z ERROR pulling demo-app:1.2 failed: context deadline exceeded

{"level":"info","time":"2026-11-10T11:58:02Z","caller":"agent.go:212","message":"connected to IronFlock"}

Wann der Befehl ablehnt

Ein --since, das weder eine Dauer noch ein Zeitpunkt ist, eine negative Dauer und ein --lines, das weder eine Zahl noch all ist, sind falsche Befehlszeilen (Exit-Code 2). Der Befehl lehnt mit Exit-Code 3 ab, wenn er nicht als root läuft und wenn kein Agent installiert ist (die Meldung nennt agent install -c <file>).