Polecenia agenta urządzenia

Polecenia ironflock agent podłączają maszynę z Linuksem do IronFlock jako urządzenie i od tej chwili dbają o agenta urządzenia. Za ich pomocą instalujesz agenta, przekazujesz mu inną konfigurację urządzenia lub inne proxy, aktualizujesz, zatrzymujesz i uruchamiasz go, czytasz jego log i ponownie go usuwasz.

Agent urządzenia

Agent urządzenia to program, który podłącza maszynę do IronFlock jako urządzenie i uruchamia w Dockerze aplikacje projektu urządzenia. To, jakim urządzeniem stanie się maszyna, określa plik konfiguracji urządzenia (.flock), który IronFlock Studio wydaje dla każdego urządzenia (Podłączanie urządzeń).

Każde polecenie agenta wymaga roota i działa w Linuksie. Bez roota kończy się kodem wyjścia 3 i samo nie wywołuje sudo (Uprawnienia roota). W macOS polecenia agenta kończą się kodem wyjścia 3, zanim cokolwiek sprawdzą; uruchamiaj je na maszynie z Linuksem albo z Maca z --host. Na urządzeniu z IronFlockOS obraz dostarcza agenta razem z systemem: agent install i agent remove odmawiają tam działania, a agent configure -c rejestruje urządzenie z innym plikiem .flock.

Każde polecenie przyjmuje też flagi globalne --yes, --json, --download-base, --host, --hosts i --parallel (Flagi globalne). Pytanie wymaga terminala; bez niego podaj --yes (Pytania i potwierdzenie).

Z --host polecenie działa na innej maszynie przez SSH (Zdalne maszyny przez SSH). Na kilku maszynach jednocześnie (--host podane więcej niż raz albo --hosts) agent restart, agent start i agent logs działają bez zmian, tyle że agent logs --follow nie działa z --json. agent stop, agent update, agent configure i agent remove wymagają tam --yes, ponieważ nikt nie jest pytany, a agent configure nie przyjmuje tam -c, ponieważ plik .flock opisuje jedno urządzenie. agent install działa na jednej maszynie naraz.

Jak wygląda zainstalowany agent

Przy każdym starcie agent sam zapisuje też kilka ustawień hosta: slice ironflock.slice, w którym działa i który rezerwuje dla niego pamięć, watchdog systemd, ustawienia jądra na wypadek awarii oraz limit rozmiaru dziennika systemd.

Na maszynie skonfigurowanej przez wcześniejszy instalator IronFlock agent może nadal być w starszym układzie /opt/reagent (usługa reagent.service, log /var/log/reagent.log), który agent sam przenosi do /opt/ironflock/device-agent. ironflock status pokazuje, jaki układ ma maszyna, a opisane niżej sytuacje odmowy wymieniają przypadki, w których ma to znaczenie.

ironflock agent install

Instaluje agenta urządzenia w /opt/ironflock/device-agent, Dockera, gdy go brakuje, oraz standardowe ustawienia hosta urządzenia, a następnie podłącza maszynę do IronFlock jako urządzenie z pliku .flock. Agent startuje od razu i od tej chwili sam się aktualizuje.

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

Działa w: Linuksie opartym na Debianie lub Ubuntu, z systemd; nie na IronFlockOS. Root: wymagany. Pyta: przed instalacją pakietów i Dockera oraz o każde standardowe ustawienie hosta; --yes odpowiada na każde pytanie wartością domyślną.

Maszyna potrzebuje dostępu do internetu, do serwera pobierania podanego w --download-base (Bazowy adres pobierania) albo do kopii lustrzanej pobierania tego Appliance, który wskazuje plik .flock (Skąd pochodzi agent). Hosty, do których musi docierać urządzenie, wymienia strona Wymagania sieciowe.

Skąd pochodzi agent

Agent to jego mapa kanałów, jego plik binarny oraz pliki .sha256 i .sig tego pliku binarnego. Polecenie pobiera je:

1. Z --download-base, a w przeciwnym razie z IRONFLOCK_DL_BASE: tylko z tego serwera.
2. W przeciwnym razie z kopii lustrzanej pobierania tego IronFlock Appliance, który plik .flock podaje jako swój serwer aktualizacji (update_url), gdy jej host nie należy do chmury IronFlock. W ten sposób instaluje się maszyna, która dociera do Appliance, ale nie do ironflock.com. Plik .flock z chmury IronFlock korzysta z chmury.
3. W przeciwnym razie z chmury IronFlock, https://instance-registry.ironflock.com/dl.

Polecenie podaje bazowy adres na stderr: Download base: ... (from the device's .flock), a w pozostałych przypadkach (from --download-base), (from IRONFLOCK_DL_BASE) lub (from default).

Przy kopii lustrzanej Appliance pliki pochodzą najpierw z kopii lustrzanej, a tam, gdzie kopia lustrzana ich nie udostępnia, z tej samej ścieżki pod bazowym adresem pobierania chmury IronFlock:

• Mapa kanałów — gdy kopia lustrzana w danej chwili jej nie udostępnia (brak odpowiedzi, brak mapy, status błędu), wszystko pochodzi z chmury, a wersją jest ta, którą podaje mapa chmury. Mapa, którą kopia lustrzana udostępnia, ale która zostaje odrzucona (jej podpis, brak wersji), kończy instalację błędem, tak jak z każdego serwera.
• Plik binarny, jego .sha256 i jego .sig — każdy z nich, którego kopia lustrzana nie udostępnia, pochodzi z chmury. Gdy pliki z kopii lustrzanej nie przejdą weryfikacji (suma kontrolna, podpis), wszystkie trzy pochodzą z chmury.

Każde przejście na chmurę to wiersz Warning: ... na stderr, z kopią lustrzaną, plikiem i przyczyną, a z --json wpis w warnings wyniku. Gdy pliku nie udostępnia ani kopia lustrzana, ani chmura, instalacja kończy się jednym błędem, który podaje oba źródła i obie przyczyny (neither the appliance's mirror ... nor the IronFlock cloud gives ...).

Kopia lustrzana jest serwerem aktualizacji z pliku .flock, a ten omija proxy (Proxy). Kopia lustrzana HTTPS z certyfikatem własnego CA Appliance działa tylko tam, gdzie system maszyny ufa temu CA. Pakiety dystrybucji i Docker nadal pochodzą z ich własnych serwerów, a install.sh i ironflock z ironflock.com; z --host plik ironflock trafia na maszynę z twojego komputera.

Testy przed instalacją

Zanim cokolwiek zmieni, polecenie wykonuje te testy ironflock doctor, które mówią, czy instalacja może się powieść: system, systemd, disk_space, clock, dns, proxy, download_tree, device_endpoint, docker_registry i update_server. Wykonuje je dla pliku .flock z -c, z bazowym adresem pobierania i flagami proxy instalacji.

Cztery z nich zatrzymują instalację, gdy się nie powiodą, ponieważ instalacja na pewno by się wtedy nie powiodła albo przerwałaby się w połowie:

Komunikat podaje test, jego ustalenie i wskazówkę. Każde inne ustalenie to ostrzeżenie na stderr, a instalacja trwa dalej: agent łączy się, aktualizuje i pobiera swoje aplikacje, gdy tylko pozwoli na to sieć. Wynik warning lub skipped nigdy nie zatrzymuje instalacji. Uruchom ironflock doctor -c device.flock, aby przed instalacją zobaczyć wszystkie testy.

Kroki

1. Podaje pakiety, które zainstaluje, i pyta. Instaluje je przez apt.
2. Instaluje Dockera, gdy maszyna go nie ma, i najpierw o to pyta.
3. Pobiera agenta z kanału produkcyjnego i weryfikuje go na podstawie sumy kontrolnej i podpisu. Instalacja, która nie może uzyskać zweryfikowanego agenta, zatrzymuje się tutaj, przed którymkolwiek z kolejnych kroków.
4. Konfiguruje Dockera: proxy, gdy je podano, a dla Dockera, który przyszedł z tą instalacją lub nie przechowuje jeszcze niczego, także data-root w folderze agenta. Docker, który przechowuje obrazy lub kontenery, zachowuje swoją konfigurację i swoje dane.
5. Konfiguruje standardowe ustawienia hosta (tabela poniżej). Każde z nich to wybór w terminalu; --yes przyjmuje wartość domyślną.
6. Instaluje agenta w /opt/ironflock/device-agent i go uruchamia.

Instalacja dodaje też baner logowania. Wszystko, co zmienia instalacja, jest zapisywane w /opt/ironflock/device-init/installed.json. Gdy nie powiedzie się któryś krok, począwszy od kroku 4, błąd mówi, że próba została odnotowana i że to samo polecenie uruchomione ponownie najpierw ją cofnie. Gdy polecenie znajdzie taką wcześniejszą próbę, cofa ją po pomyślnych testach: wymienia, co cofa, pyta, a potem instaluje od nowa.

Proxy

Flagi proxy ustawiają firmowe proxy dla pobierania podczas instalacji, dla Dockera i dla agenta. Każde ustawienie pochodzi ze swojej flagi, a w przeciwnym razie ze zmiennych środowiskowych HTTP_PROXY, HTTPS_PROXY i NO_PROXY (lub ich wersji pisanych małymi literami).

Adres URL proxy wygląda jak http://proxy.example.com:3128; działają też https:// i socks5://, a adres URL bez schematu oznacza http://. Gdy proxy wymaga logowania, adres URL podaje użytkownika bez hasła, http://[email protected]:3128, a hasło podaje --proxy-password-file. Polecenie wstawia hasło do adresów URL z flag, które wskazują użytkownika.

Ostrzeżenie: Nigdy nie wpisuj hasła proxy do adresu URL. Wiersze poleceń są widoczne w ps i w historii powłoki, dlatego adres URL z hasłem jest odrzucany jako błędny wiersz poleceń, a komunikat błędu go nie powtarza. Zapisz hasło w jednym wierszu pliku albo przekaż je potokiem z --proxy-password-file /dev/stdin (Sekrety).

Poza hostami z --no-proxy proxy omijają (NO_PROXY): localhost, 127.0.0.1 i ::1 oraz serwer pobierania i serwer aktualizacji z pliku .flock (jego update_url), gdy nie są hostami chmury IronFlock, tak jak Appliance lub kopia lustrzana w sieci LAN. Hosty chmury IronFlock (ironflock.com, ironflock.dev i hosty pod nimi oraz storage.googleapis.com) są w internecie i idą przez proxy.

Instalacja zapisuje proxy Dockera i agenta w /etc/ironflock/proxy.env, który odczytuje tylko root (tryb 0600), a Docker restartuje się, aby z niego korzystać. Drop-iny systemd ironflock-proxy.conf dla docker.service i ironflock-device-agent.service wskazują ten plik i same nie zawierają żadnego ustawienia, więc systemctl show pokazuje każdemu użytkownikowi nazwę pliku i nic z jego zawartości. Własny drop-in hosta dla Dockera (docker.service.d/http-proxy.conf) pozostaje; ustawienia IronFlock mają pierwszeństwo przed jego wierszami Environment=, a ostrzeżenie go wskazuje. daemon.json z proxies je zachowuje, ponieważ Docker stosuje je przed wszystkimi innymi.

Aby później zmienić ustawienia, użyj agent configure. Proxy całej lokalizacji opisuje strona Za firmowym proxy.

Przykłady

# Zainstaluj agenta; polecenie pyta przed każdym krokiem
sudo ironflock agent install -c device.flock
# Zainstaluj bez pytań i nie pozwól urządzeniu przechodzić w stan uśpienia
sudo ironflock agent install -c device.flock --yes --disable-suspend
# Zainstaluj za proxy, które nie wymaga logowania
sudo ironflock agent install -c device.flock --https-proxy http://proxy.example.com:3128
# Zainstaluj za proxy z logowaniem; hasło pochodzi z pliku
sudo ironflock agent install -c device.flock --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt

Wynik

$ 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 występuje w wyniku tylko wtedy, gdy plik pochodził z chmury IronFlock zamiast z kopii lustrzanej Appliance: po jednym wpisie na każdy taki plik, tak jak podają to wiersze Warning:.

Kiedy polecenie odmawia

Błędny wiersz poleceń kończy się kodem wyjścia 2, zanim cokolwiek się uruchomi: adres URL proxy z hasłem; adres URL proxy, który wskazuje użytkownika, bez --proxy-password-file; --proxy-password-file bez adresu URL proxy, który wskazuje użytkownika; wartość, która nie jest adresem URL proxy. Dotyczy to także zmiennej proxy ze środowiska, która nie jest adresem URL proxy; błąd podaje zmienną, a nie jej wartość.

Polecenie odmawia działania z kodem wyjścia 3 i niczego nie zmienia, gdy:

• nie działa jako root albo maszyna nie działa pod Linuksem;
• maszyna działa pod IronFlockOS, co polecenie sprawdza przed wszystkim innym, z rootem lub bez roota. Obraz dostarcza agenta i ironflock razem z systemem, a każda aktualizacja systemu zastępuje system w całości. Komunikat mówi, że urządzenie zarejestruje się przy następnym starcie z plikiem .flock na swojej partycji IRONFLOCKOS i że agent configure -c zarejestruje je od razu. Na pendrivie instalacyjnym IronFlockOS mówi, że pendrive nie jest urządzeniem;
• agent jest już zainstalowany, także w starszym układzie /opt/reagent. Komunikat wskazuje agent configure i agent remove;
• agent właśnie przenosi maszynę ze starszego układu;
• wcześniejsza instalacja przeniosła data-root Dockera i zatrzymała się, zanim skonfigurowała agenta, a Docker od tego czasu przechowuje obrazy lub kontenery: cofnięcie tej próby by je usunęło;
• nie powiedzie się jeden z testów system, systemd, disk_space lub download_tree. --yes niczego tu nie zmienia.

Odpowiedź „nie” na pytanie albo pytanie bez terminala i bez --yes kończy polecenie kodem wyjścia 4. Krok, który się nie powiedzie, kończy je kodem wyjścia 1.

ironflock agent configure

Zmienia to, co skonfigurowała instalacja: plik .flock urządzenia, firmowe proxy Dockera i agenta albo jedno i drugie. Restartuje to, co musi zacząć korzystać ze zmiany.

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

Działa w: Linuksie z zainstalowanym agentem; na IronFlockOS tylko z -c. Root: wymagany. Pyta: przed restartem Dockera dla nowych ustawień proxy; --yes odpowiada.

Podaj -c, flagę proxy albo jedno i drugie. Bez żadnej z nich nie ma nic do zmiany: to błędny wiersz poleceń (kod wyjścia 2).

Inny plik .flock

Z -c agent dostaje podany plik .flock i się restartuje: maszyna staje się urządzeniem z tego pliku .flock. Aplikacje i ich dane pozostają. Gdy instalacja skonfigurowała użytkownika SSH, użytkownik SSH podąża za plikiem .flock:

• Ten sam właściciel projektu, inny klucz urządzenia — stary klucz nie jest już akceptowany, a nowy jest.
• Inny właściciel projektu — nowy właściciel dostaje swojego użytkownika SSH, a użytkownik SSH pierwszego właściciela znika tak, jak usuwa go agent remove: reguła sudo, klucz oraz konto z folderem domowym, jeśli utworzyła je instalacja.
• Plik .flock bez klucza urządzenia — użytkownik SSH znika, a nowy nie powstaje.

Gdy urządzenie zmienia właściciela, polecenie może uruchamiać właśnie pierwszy właściciel, przez SSH, z tego samego konta, które znika, a usunięcie konta kończy jego sesje. Dlatego polecenie działa w tej kolejności: konfiguruje konto nowego właściciela (użytkownik, klucz, reguła sudo), restartuje agenta z nowym plikiem .flock i dopiero potem odbiera pierwszemu właścicielowi regułę sudo, sesje i konto (albo, przy tym samym właścicielu, tylko stary klucz). Urządzenie ma nową drogę dostępu i jest online, zanim zniknie stara. Zanim sesje się zakończą, mówi o tym wiersz na stderr, na przykład Removing the account anna, ...: a session of anna ends here.

• Gdy agent nie zrestartuje się z nowym plikiem .flock, pierwszy właściciel zachowuje dostęp: ktoś musi mieć możliwość dostania się do urządzenia.
• Gdy nie powiodło się tylko utworzenie użytkownika SSH nowego właściciela, dostęp pierwszego właściciela i tak znika: urządzenie zmieniło właściciela i jest online.
• To, czyj dostęp ma jeszcze zniknąć, jest odnotowane w /opt/ironflock/device-init/installed.json (users_to_remove). Każde późniejsze agent configure -c i agent remove próbuje ponownie.
• Konto, które nowy plik .flock konfiguruje ponownie, nigdy nie jest usuwane (właściciel A, potem B, potem znów A).
• Od pierwszej zmiany utrata terminala lub sesji SSH nie zatrzymuje polecenia.

Przez --host kopia pliku .flock na maszynie jest usuwana, gdy tylko polecenie ją odczyta. Gdy konto SSH z --host jest kontem, które znika, sesja SSH kończy się razem z kontem: twoje uruchomienie kończy się wtedy kodem wyjścia 255, jak po utracie połączenia, a polecenie na maszynie działa do końca. Folder uruchomienia ironflock.XXXXXXXXXX z plikiem binarnym zostaje wtedy na maszynie; w folderze tymczasowym zostaje do jego wyczyszczenia, w folderze domowym konta znika razem z kontem.

Na IronFlockOS

Z -c polecenie rejestruje urządzenie tak, jak IronFlockOS rejestruje je przy pierwszym rozruchu każdego nowego slotu systemowego, zarówno na urządzeniu, które już się zarejestrowało, jak i na takim, które jeszcze tego nie zrobiło. Podany plik .flock staje się kopią agenta, /opt/ironflock/device-agent/device-config.flock na /data, a urządzenie jest z niego konfigurowane w tej kolejności: użytkownik SSH właściciela projektu, WiFi, nazwa hosta z nazwy urządzenia (chyba że /etc/ironflockos/enroll.conf mówi hostname-from-flock=no), agent, zrestartowany z nowym plikiem .flock, a na końcu usunięcie dostępu poprzedniego właściciela.

Następna aktualizacja systemu rejestruje swój nowy slot systemowy z tej samej kopii. Podany plik zostaje tam, gdzie jest. Krok, który się nie powiedzie, nie przeszkadza agentowi zrestartować się z nowym plikiem .flock, ale dostęp pierwszego właściciela znika dopiero po restarcie agenta. Polecenie kończy się wtedy kodem wyjścia 1 i wymienia każdy krok, który się nie powiódł; uruchom to samo polecenie ponownie, aby je powtórzyć.

Flagi proxy są na IronFlockOS odrzucane. IronFlockOS przechowuje proxy Dockera, agenta i zegara systemowego w /etc/ironflockos/proxy.conf na /data, a plik proxy.conf na partycji IRONFLOCKOS zastępuje je przy następnym starcie.

Ustawienia proxy

• Każda podana flaga proxy zastępuje swoje ustawienie, a pozostałe zostają. Samo --https-proxy zmienia proxy HTTPS i zachowuje proxy HTTP oraz hosty, które je omijają.
• Hasło z --proxy-password-file trafia do podanych adresów URL, które wskazują użytkownika. Gdy nie podano żadnego adresu URL, trafia do tych adresów URL z ustawień urządzenia, które wskazują użytkownika, więc nowe hasło ustawia się samym plikiem.
• --no-proxy oraz pierwsze proxy urządzenia, które dotąd go nie miało, obejmują też localhost, 127.0.0.1, ::1 i serwer aktualizacji z pliku .flock agenta, gdy nie jest hostem chmury IronFlock (na przykład serwer Appliance).
• --remove-proxy usuwa ustawienia. Nie przyjmuje żadnej innej flagi proxy.
• Zmienne proxy z twojego środowiska niczego tu nie zmieniają: liczą się tylko flagi.

Lista hostów, które omijają proxy, pozostaje taka, jaką polecenie zastało, chyba że --no-proxy podaje inną. Gdy ta lista zawiera host chmury IronFlock, ostrzeżenie go wskazuje i podaje polecenie agent configure --no-proxy, które ustawia listę bez niego. Urządzenie, które dociera do internetu tylko przez proxy, nie może zaktualizować swojego agenta, dopóki serwer pobierania chmury, instance-registry.ironflock.com, jest na tej liście.

Ustawienia są przechowywane w /etc/ironflock/proxy.env, który odczytuje tylko root, i wskazywane przez drop-iny ironflock-proxy.conf dla docker.service i ironflock-device-agent.service. Gdy ustawienia się zmieniają, polecenie pokazuje je przed zmianą i po niej, bez hasła. Potem restartują się Docker i agent. Restart Dockera na chwilę zatrzymuje aplikacje urządzenia, więc polecenie o tym mówi i pyta; --yes odpowiada. Gdy hasło przychodzi na stdin, nie ma terminala, w którym można zadać pytanie: podaj --yes.

• Docker się nie restartuje, a polecenie o nic nie pyta, gdy daemon.json Dockera ustawia proxies (Docker stosuje je przed tymi ustawieniami) oraz gdy nic się nie zmienia.
• Jednostka, której brakuje tylko jej drop-inu, dostaje go i restartuje się tylko ta jednostka.
• Własny drop-in hosta dla Dockera pozostaje bez zmian. Inny drop-in agenta lub Dockera, który ustawia zmienną proxy, jest wskazywany w ostrzeżeniu; ustawienia IronFlock zastępują go dla każdej zmiennej, którą ustawiają. Drop-in lub daemon.json z hasłem proxy, które może odczytać każdy użytkownik, również jest wskazywany w ostrzeżeniu.
• Gdy restart Dockera się nie powiedzie, agent i tak się restartuje, i na odwrót. Błąd (kod wyjścia 1) podaje jednostki, które nadal działają ze starymi ustawieniami, oraz polecenie systemctl restart, które je zastosuje; drugie uruchomienie zastaje ustawienia na miejscu i niczego nie restartuje.
• Gdy ustawień nie da się zapisać, nic się nie restartuje, a błąd każe uruchomić polecenie ponownie.

Ustawienia proxy, które starsza instalacja zapisała w wierszach Environment= drop-inów http-proxy.conf, gdzie każdy użytkownik może je odczytać przez systemctl show, razem z hasłem, przenoszą się do /etc/ironflock/proxy.env przy każdym uruchomieniu agent configure, także takim z samym -c. Kopia starych plików nie jest zachowywana. Z reguły przeniesienie zachowuje wartości, więc niczego nie restartuje i o nic nie pyta; gdy zmienia proxy, którego używa jakaś jednostka, polecenie mówi dlaczego, pokazuje proxy tej jednostki przed zmianą i po niej oraz pyta. Wartość, której plik ustawień nie może przechować (apostrof w hoście lub na liście hostów omijających proxy, znak sterujący), nie jest przenoszona: uruchomienie bez flag proxy ją zostawia, ostrzega i wskazuje flagę, która podaje tę wartość od nowa.

Przykłady

# Zmień tę maszynę w urządzenie z innego pliku .flock
sudo ironflock agent configure -c new-device.flock
# Ustaw proxy HTTPS z logowaniem; hasło pochodzi z pliku
sudo ironflock agent configure --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt
# Ustaw samo nowe hasło proxy, odczytane ze stdin, bez pytania
sudo ironflock agent configure --proxy-password-file /dev/stdin --yes < proxy-password.txt
# Usuń ustawienia proxy: Docker i agent łączą się bezpośrednio
sudo ironflock agent configure --remove-proxy

Wynik

$ 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.

Na IronFlockOS -c zgłasza rejestrację:

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"]}

Kiedy polecenie odmawia

Błędny wiersz poleceń kończy się kodem wyjścia 2: nic do zmiany; --remove-proxy z inną flagą proxy; adres URL proxy z hasłem; adres URL proxy, który wskazuje użytkownika, bez --proxy-password-file; --proxy-password-file z adresami URL, z których żaden nie wskazuje użytkownika; wartość, która nie jest adresem URL proxy ani listą hostów.

Polecenie odmawia działania z kodem wyjścia 3 i niczego nie zmienia, gdy:

• nie jest zainstalowany żaden agent (komunikat wskazuje agent install), z wyjątkiem IronFlockOS, gdzie -c rejestruje urządzenie, które jeszcze się nie zarejestrowało;
• agent właśnie przenosi maszynę ze starszego układu;
• podano flagi proxy, a agent nadal działa w starszym układzie /opt/reagent. Gdy agent przeniesie maszynę (ironflock status pokazuje układ), to samo polecenie zadziała;
• podano flagi proxy na IronFlockOS, z -c lub bez;
• na urządzeniu bez proxy podano samo --no-proxy lub samo --proxy-password-file albo podano sam plik z hasłem, gdy żaden adres URL proxy urządzenia nie wskazuje użytkownika;
• flagi proxy zachowują wartość w starej postaci, której /etc/ironflock/proxy.env nie może przechować; komunikat wskazuje flagę, która podaje ją od nowa.

Na IronFlockOS flaga -c jest odrzucana z kodem wyjścia 3, gdy rejestracja nie zachowałaby pliku .flock:

• zażądano resetu do ustawień fabrycznych, który jeszcze się nie zaczął (/boot/efi/factory-reset.conf, który zapisuje os reset), albo reset już się zaczął (/boot/efi/factory-reset.keep): następny start wymazałby to, co konfiguruje polecenie;
• reset do ustawień fabrycznych jest otwarty lub został zaniechany i trzyma pliki, które z nim przyszły (/run/ironflockos/factory-reset-hold; więcej mówi ironflock status);
• nie udało się zamontować /data, więc kopia agenta trafiłaby do slotu systemowego. Drogą jest wtedy plik .flock na partycji IRONFLOCKOS;
• na partycji IRONFLOCKOS leży plik .flock; urządzenie zarejestruje się z nim przy następnym starcie, a komunikat go wskazuje;
• polecenie działa na pendrivie instalacyjnym IronFlockOS, który nie jest urządzeniem;
• system nie ma /usr/lib/ironflock/image.json albo ma agenta w starszym układzie.

ironflock agent update

Zleca agentowi samoaktualizację do wydania z jego kanału i śledzi, co agent robi. Agent szuka nowszego wydania przy każdym starcie: polecenie go restartuje i podaje rezultat. Urządzenie jest przez chwilę offline w IronFlock; jego aplikacje działają dalej.

ironflock agent update [flags]

Działa w: Linuksie, z zainstalowanym agentem. Root: wymagany. Pyta: tak, gdy już powie, co zrobi restart; --yes odpowiada.

Polecenie nie ma własnych flag i nie przyjmuje wersji. Agent podąża za swoim kanałem (production albo test na platformie testowej IronFlock), korzystając ze swojego serwera aktualizacji: update_url z jego pliku .flock (kopia lustrzana Appliance), a w przeciwnym razie chmura IronFlock. --download-base tego nie zmienia.

Co robi agent, w tej kolejności:

1. Odczytuje wydanie ze swojego kanału. Wydanie, które dwukrotnie nie powiodło się na tym urządzeniu, nie jest pobierane ponownie, dopóki nie pojawi się nowsze.
2. Pobiera nowsze wydanie do swojego folderu i sprawdza jego podpis.
3. Umieszcza nową wersję na miejscu i restartuje się do niej 10 sekund po pobraniu. Wstrzymuje aktualizację, gdy ostatnie połączenie z IronFlock miał od 12 minut do doby temu: aktualizacja jest aktywowana z wersji, o której wiadomo, że się łączy.
4. Nowa wersja jest w okresie próbnym: musi połączyć się z IronFlock w ciągu 10 minut od startu i działać przez 2 minuty. Jeśli tak się nie stanie albo wcześniej trzykrotnie się zatrzyma, agent wraca do poprzedniej wersji.
5. Po wycofaniu musi się połączyć poprzednia wersja. Wtedy winna była nowa wersja: zostanie wypróbowana jeszcze raz przy następnej aktualizacji, a po drugim niepowodzeniu jest blokowana do czasu nowszego wydania. Gdy poprzednia wersja również nie połączy się w ciągu 10 minut, agent obwinia sieć, a nowa wersja zostanie wypróbowana ponownie przy następnej aktualizacji.

Polecenie śledzi to w update-state.json w folderze agenta i w logu agenta; nie odczytuje z nich niczego sprzed restartu. Jego postęp trafia na stderr jako wiersze tekstu, także z --json. Pobieranie raz na minutę pokazuje, ile już pobrano.

Przy kodzie wyjścia 1 wynik i tak jest zapisywany, a stderr dostaje wiersz Error:. Z --json nie następuje po nim obiekt błędu: stdout zawiera wynik.

Przykłady

# Zaktualizuj agenta; polecenie pyta przed restartem
sudo ironflock agent update
# Zaktualizuj bez pytania i odczytaj rezultat jako JSON
sudo ironflock agent update --yes --json

Wynik

$ 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.

Agent, który jest aktualny, i agent, którego nowa wersja została wycofana:

{"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"}

Kiedy polecenie odmawia

Polecenie odmawia działania z kodem wyjścia 3, gdy nie jest zainstalowany żaden agent (komunikat wskazuje agent install), gdy agent przenosi maszynę ze starszego układu, gdy agent działa w starszym układzie (jego aktualizacje nie zapisują stanu, który polecenie mogłoby śledzić) oraz gdy agent jest starszy niż wersja 1.3.0, pierwsza, która sama się aktualizuje w ramach swojej jednostki.

Kończy się kodem wyjścia 1 i błędem, który mówi, gdzie szukać, gdy restart się nie powiedzie oraz gdy aktualizacja nie posuwa się naprzód w czasie przewidzianym przez agenta: sprawdzenie przez agenta w ciągu 3 minut od restartu, pobieranie w ciągu 30 minut, aktywacja w ciągu 3 minut, każdy start nowej wersji w okresie próbnym w ciągu 12 minut, ocena agenta po wycofaniu w ciągu 12 minut, a wszystko razem w ciągu 84 minut. Agent kontynuuje samodzielnie; ironflock status pokazuje, na jakim jest etapie.

Ctrl-C przerywa śledzenie, a nie aktualizację, i kończy polecenie kodem wyjścia 130.

ironflock agent remove

Usuwa agenta urządzenia i cofa to, co odnotowała jego instalacja. Sam Docker i pakiety pozostają zainstalowane.

ironflock agent remove [flags]

Działa w: Linuksie, z zainstalowanym agentem; nie na IronFlockOS. Root: wymagany. Pyta: tak, gdy już wymieni, co usunie. Pytanie ma wstępnie wybraną odpowiedź „Nie”: sam Enter niczego nie usuwa.

Polecenie nie ma własnych flag. Usuwa:

• Agenta — agenta, jego bazę danych i /opt/ironflock/device-agent. Aplikacje urządzenia i ich dane znikają razem z nim, gdy Docker przechowuje je w folderze agenta.
• Użytkownika SSH — konto tylko wtedy, gdy utworzyła je instalacja. Z konta, które istniało wcześniej, znika tylko klucz urządzenia z jego authorized_keys, a sam plik nadal należy do użytkownika. Znika też dostęp wcześniejszego właściciela projektu, którego usunięcie przez agent configure -c się nie powiodło; lista oznacza go dopiskiem „(a removal that had failed)”.
• Standardowe ustawienia hosta — profil WiFi, baner logowania i zamaskowane cele uśpienia.
• Pliki, które instalacja zapisała lub zastąpiła — wracają oryginały, z trybem, właścicielem i grupą.
• Ustawienia proxy — /etc/ironflock/proxy.env z drop-inami, które go wskazują, oraz ustawienia proxy, które starsza instalacja zostawiła w drop-inach http-proxy.conf. Nic nie wraca na ich miejsce: potem Docker nie ma proxy od IronFlock, a polecenie nigdzie nie zapisało hasła proxy. Gdy Docker miał proxy od IronFlock, mówi o tym lista przed pytaniem.
• Ustawienia, które agent sam zapisał na hoście — slice ironflock.slice z drop-inem 10-ironflock-resources.conf jego jednostki, watchdog systemd (/etc/systemd/system.conf.d/10-ironflock-watchdog.conf), ustawienia jądra na wypadek awarii (/etc/sysctl.d/60-ironflock-crash-recovery.conf; jądro zachowuje je do następnego rozruchu) i limit dziennika systemd (/etc/systemd/journald.conf.d/10-ironflock.conf).
• Dane logowania agenta do rejestrów — gdy agent się zatrzyma, polecenie uruchamia docker logout dla rejestru wskazanego w pliku .flock (docker_registry_url), a na urządzeniu Appliance także dla registry.<appliance_domain>. Żadne inne dane logowania w /root/.docker/config.json nie są ruszane. Brak Dockera lub jego błąd nie zatrzymuje usuwania; wiersz mówi, których danych logowania nie usunięto.

Własny drop-in hosta dla Dockera pozostaje bez zmian. Docker, który nie restartuje się przy usuwaniu (jego dane nie były w folderze agenta), używa proxy, z którym wystartował, aż do następnego restartu.

Polecenie wymienia na stderr, co usunie, a potem pyta. Z --json ta lista to pole removed wyniku. Gdy polecenie zacznie usuwać, utrata terminala lub sesji SSH go nie zatrzymuje: znikający użytkownik SSH zabiera ze sobą swoje sesje, być może także tę, w której działa polecenie, a usuwanie trwa do końca.

Przykłady

# Usuń agenta; polecenie wymienia, co zniknie, i pyta
sudo ironflock agent remove
# Usuń agenta bez pytania
sudo ironflock agent remove --yes

Wynik

$ 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"]}

Kiedy polecenie odmawia

Polecenie odmawia działania z kodem wyjścia 3, gdy nie jest zainstalowany żaden agent oraz gdy agent przenosi maszynę ze starszego układu. Na IronFlockOS odmawia przed wszystkim innym, z rootem lub bez roota: obraz dostarcza agenta razem z systemem, a każda aktualizacja systemu i następna rejestracja skonfigurowałyby go ponownie. Komunikat wskazuje ironflock os reset, które przywraca urządzenie do stanu świeżo zapisanego IronFlockOS, bez jego tożsamości w IronFlock. Na pendrivie instalacyjnym IronFlockOS mówi, że pendrive nie jest urządzeniem.

Odpowiedź „nie” albo pytanie bez terminala i bez --yes kończy polecenie kodem wyjścia 4.

ironflock agent restart

Restartuje usługę agenta i sprawdza, czy agent znów działa: jego jednostka musi działać przez pięć sekund z jednym procesem. Przez te sekundy urządzenie jest offline w IronFlock; aplikacje działają dalej.

ironflock agent restart [flags]

Działa w: Linuksie, z zainstalowanym agentem. Root: wymagany. Pyta: o nic.

Polecenie nie ma własnych flag. Usługa to ironflock-device-agent.service. Gdy polecenie działa w terminalu, który przechodzi przez agenta (terminal urządzenia w IronFlock Studio albo SSH przez IronFlock), restart kończy tę sesję; urządzenie wraca w ciągu minuty.

# Zrestartuj agenta
sudo ironflock agent restart
# Zrestartuj go i odczytaj nowy proces jako JSON
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 to stan jednostki po restarcie, nazwany tak jak w ironflock status. main_pid to proces agenta, nowy po każdym restarcie.

Odmawia działania z kodem wyjścia 3, gdy nie jest zainstalowany żaden agent (komunikat wskazuje agent install -c <file>), gdy agent przenosi maszynę ze starszego układu oraz gdy systemd nie zna jednostki agenta (komunikat wskazuje agent remove).

Kończy się błędem z kodem wyjścia 1, gdy agent nie wystartuje: systemd nie może uruchomić jednostki albo jej proces kończy się w ciągu tych pięciu sekund. Błąd podaje jednostkę i miejsca, w których są jej ostatnie wiersze logu: log agenta (agent logs) i dziennik systemd (journalctl -u <unit>).

ironflock agent stop

Zatrzymuje usługę agenta. Urządzenie przechodzi w IronFlock w stan offline, a razem z agentem znika zdalny dostęp przez IronFlock: sesja, która przyszła tą drogą (terminal urządzenia w IronFlock Studio, SSH przez IronFlock), się kończy, a IronFlock nie może dotrzeć do urządzenia, dopóki agent znów nie zacznie działać. Aplikacje działają dalej, ponieważ uruchamia je Docker, a nie agent.

ironflock agent stop [flags]

Działa w: Linuksie, z zainstalowanym agentem. Root: wymagany. Pyta: tak, gdy już powie, co zakończy zatrzymanie agenta; --yes odpowiada.

Polecenie nie ma własnych flag. agent start ponownie uruchamia agenta, podobnie jak następny rozruch. Zatrzymanego agenta nie da się ponownie uruchomić przez IronFlock. Agent, który nie działa, nie ma czego zatrzymywać; polecenie o nic wtedy nie pyta, a wynik nie ma pola action.

# Zatrzymaj agenta; polecenie mówi, co to zakończy, i pyta
sudo ironflock agent stop
# Zatrzymaj go bez pytania
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"}

Odmawia działania z kodem wyjścia 3 tak jak agent restart. Odpowiedź „nie” albo pytanie bez terminala i bez --yes kończy je kodem wyjścia 4.

ironflock agent start

Uruchamia usługę agenta, gdy nie działa, i sprawdza, czy agent wystartował, tak jak agent restart: jego jednostka musi działać przez pięć sekund z jednym procesem. Agent, który już działa, pozostaje bez zmian, a wynik nie ma wtedy pola action.

ironflock agent start [flags]

Działa w: Linuksie, z zainstalowanym agentem. Root: wymagany. Pyta: o nic. Polecenie nie ma własnych flag.

# Uruchom agenta
sudo ironflock agent start
# Uruchom go i odczytaj jego proces jako JSON
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.

Z --json, dla agenta, który już działa:

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

Odmawia i kończy się błędem tak jak agent restart: kod wyjścia 3, gdy nie jest zainstalowany żaden agent, gdy agent przenosi maszynę ze starszego układu oraz gdy systemd nie zna jednostki agenta; kod wyjścia 1, gdy agent nie wystartuje.

ironflock agent logs

Pokazuje log agenta, /var/log/ironflock/device-agent.log, oraz pliki, do których agent go zrotował. Niczego nie zmienia.

ironflock agent logs [flags]

Działa w: Linuksie, z zainstalowanym agentem; czyta pliki i nie potrzebuje systemd. Root: wymagany, ponieważ agent zapisuje log tylko dla roota (tryb 0600). Pyta: o nic.

Przy 100 MB agent zmienia nazwę swojego logu na device-agent-<time>.log w tym samym folderze i zaczyna nowy; zachowuje dwa takie pliki. Polecenie czyta log i te pliki.

Agent zapisuje jeden obiekt JSON na wiersz: czas wpisu (z dokładnością do sekundy), jego poziom, komunikat i inne pola. Postać tekstowa pokazuje wpis tak, jak IronFlock Studio pokazuje log agenta: czas w UTC, poziom, komunikat i jego błąd. Wiersz, który nie jest wpisem, na przykład ślad stosu po awarii, jest pokazywany bez zmian. Znaki sterujące są zapisywane jako sekwencje ucieczki (\n, \x1b), więc wpis zajmuje w terminalu jeden wiersz i nie może sterować terminalem. Z --json każdy wiersz to jeden obiekt JSON na stdout: wpis tak, jak zapisał go agent, ze wszystkimi polami, albo {"message":...} dla wiersza, który nie jest wpisem.

• --since zaczyna od pierwszego wpisu z tego momentu lub późniejszego. Wiersze zachowują kolejność, w jakiej zapisał je agent. Wiersz bez czasu należy do wpisu przed nim.
• Z --follow wiersz jest pokazywany, gdy jest kompletny. Gdy agent zaczyna nowy plik, najpierw pojawia się reszta starego, a potem nowy od początku. Na log, który jeszcze nie istnieje, polecenie czeka. Ctrl-C kończy polecenie kodem wyjścia 0; przez --host Ctrl-C kończy uruchomienie kodem wyjścia 130.
• Gdy agent nie zapisał jeszcze żadnego logu, stderr o tym mówi, stdout pozostaje pusty, a kod wyjścia wynosi 0.

Przykłady

# Ostatnie 100 wierszy
sudo ironflock agent logs
# Wszystko z ostatniej godziny
sudo ironflock agent logs --since 1h
# Ostatnie 20 wierszy, potem każdy nowy wiersz aż do Ctrl-C
sudo ironflock agent logs --follow --lines 20
# Ostatnie dziesięć minut jako JSON, jeden obiekt na wiersz
sudo ironflock agent logs --since 10m --json

Wynik

$ 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"}

Kiedy polecenie odmawia

--since, które nie jest ani czasem trwania, ani momentem, ujemny czas trwania oraz --lines, które nie jest ani liczbą, ani all, to błędne wiersze poleceń (kod wyjścia 2). Polecenie odmawia działania z kodem wyjścia 3, gdy nie działa jako root oraz gdy nie jest zainstalowany żaden agent (komunikat wskazuje agent install -c <file>).