Logowanie i zarządzanie urządzeniami
Te polecenia komunikują się z instancją IronFlock, chmurą lub Appliance, a nie z maszyną, na której działają. ironflock login zapisuje klucz API na tej maszynie, whoami podaje konto, do którego należy klucz, a logout usuwa klucz. ironflock device create, list i delete działają następnie na urządzeniach twoich projektów. agent install, os flash i os install mogą utworzyć urządzenie za ciebie dzięki --project i --name.
Żadne z nich nie wymaga roota i wszystkie działają w Linuksie, macOS i Windows. Działają tylko na tej maszynie: --host i --hosts są odrzucane z kodem wyjścia 2, a ani klucz, ani plik poświadczeń nigdy nie trafia na inną maszynę (Zdalne maszyny przez SSH).
login i whoami wymagają instancji, której usługa API odpowiada na GET /v1/ironflock/whoami (Punkty końcowe API). Chmura IronFlock odpowiada. Instancja bez tej trasy odpowiada 404, a polecenia o tym informują. IronFlock Appliance oferuje tę trasę, gdy tylko uruchamia usługę IronFlock API; wydań Appliance, które jej jeszcze nie uruchamiają, nie można używać z tymi poleceniami. Polecenia komunikują się z API instancji i z niczym innym, a proxy biorą ze środowiska (HTTPS_PROXY, NO_PROXY), jak każde inne żądanie ironflock.
Instancja
Domyślna jest chmura. --instance, a w jej braku zmienna środowiskowa IRONFLOCK_INSTANCE, wskazuje inną instancję: Appliance. Podaj to, co masz pod ręką, a polecenie wyprowadzi z tego adres API:
| Podajesz | API to |
|---|---|
nic albo ironflock.com, studio.ironflock.com lub api.ironflock.com | https://api.ironflock.com |
domenę Appliance, factory.example.com | https://api.factory.example.com |
adres, pod którym otwierasz Studio, https://factory.example.com/projects/12 | https://api.factory.example.com |
własny host API, api.factory.example.com | https://api.factory.example.com |
Bez schematu przyjmowane jest https://. Zwykłe http jest akceptowane tylko dla adresu loopback, dla stosu na tej maszynie. Adres IP inny niż loopback jest odrzucany: do API Appliance dociera się po nazwie. Appliance w trybie zwykłego HTTP nie ma api.<domain> i login do niego nie dociera. Certyfikat instancji jest sprawdzany względem magazynu zaufanych certyfikatów tej maszyny i urzędów certyfikacji z --ca-cert (plik PEM, kilka razy dla kilku), na przykład CA twojej firmy, które podpisało certyfikat Appliance. Nic nie wyłącza tego sprawdzenia.
Plik poświadczeń
login przechowuje klucz w credentials.json w folderze ironflock w folderze konfiguracji twojego użytkownika: ~/.config/ironflock/ w Linuksie, ~/Library/Application Support/ironflock/ na Macu i %LOCALAPPDATA%\ironflock\credentials\ w Windows. Zawiera on jeden wpis na instancję i tylko ty możesz go odczytać. Plik lub folder, który inni mogą odczytać lub zmienić, nie jest używany: polecenie kończy się kodem wyjścia 3, mówi, jak to naprawić, i niczego nie zmienia.
Na potrzeby skryptów i CI IRONFLOCK_API_KEY zawiera klucz, którego każde polecenie używa zamiast zapisanego. login nigdy go nie odczytuje ani nie zapisuje.
| Zmienna | Znaczenie |
|---|---|
IRONFLOCK_INSTANCE | Instancja, gdy nie podano --instance |
IRONFLOCK_API_KEY | Klucz API używany zamiast zapisanego |
HTTPS_PROXY, NO_PROXY | Proxy dla żądań do instancji |
ironflock login
Zapisuje klucz API dla instancji, po zapytaniu instancji, czyj to klucz.
ironflock login [--key-file <file>] [--instance <domain or URL>] [--ca-cert <file>]...$ ironflock login --key-file key.txt --instance factory.example.com
Logged in to https://api.factory.example.com as operator (account 12). The key is stored in /home/operator/.config/ironflock/credentials.json.Działa w: Linuksie, macOS i Windows. Root: niepotrzebny. Pyta: o nic.
| Flaga | Znaczenie |
|---|---|
--key-file <file> | Plik lub potok, który zawiera klucz. Domyślnie: standardowe wejście, gdy nie jest terminalem |
--instance <instance> | Instancja. Domyślnie: IRONFLOCK_INSTANCE, a w jej braku chmura |
--ca-cert <file> | Urząd certyfikacji, któremu należy ufać oprócz tych z tej maszyny; kilka razy dla kilku |
- Klucz nigdy nie trafia do wiersza poleceń. Pochodzi z pliku lub potoku, a polecenie nigdy nie pyta o niego w terminalu. Bez nich kończy się kodem wyjścia 2 i mówi, jak go przekazać. Białe znaki wokół klucza są pomijane. Klucz ma 40 znaków
0-9ia-f; cokolwiek innego jest odrzucane przed jakimkolwiek żądaniem, a błąd go nie powtarza. - Zanim cokolwiek zostanie zapisane, instancja jest pytana, czyj to klucz. Klucz, którego instancja nie przyjmuje, instancja, która nie może odpowiedzieć, niezaufany certyfikat lub instancja, do której nie da się dotrzeć, kończą się kodem wyjścia 1, a to, co było zapisane wcześniej, pozostaje bez zmian.
- Logowanie do instancji, która ma już login, zastępuje go. Loginy innych instancji pozostają.
- Żądanie nie podąża za żadnym przekierowaniem, aby klucz nie trafił do innego hosta.
- Z
--jsonwynik to jeden obiekt zaction(logged_in),instance,account_id,username,scopes,restrictionicredential_file.
Umieść klucz w pliku, który tylko ty możesz odczytać, a potem się zaloguj:
(umask 077; cat > key.txt)
ironflock login --key-file key.txtWpisz lub wklej klucz do terminala po cat > key.txt, zakończ klawiszami Ctrl-D i usuń key.txt, gdy login zapisze klucz.
ironflock whoami
Podaje konto, do którego należy klucz, i pokazuje, co klucz może.
ironflock whoami [--instance <domain or URL>] [--ca-cert <file>]...$ ironflock whoami --instance factory.example.com
Instance: https://api.factory.example.com
Account: operator (12)
Scopes: devices:read, devices:write
Restriction: the projects 3
Key: stored by 'ironflock login' on 2026-11-19 10:00 UTCKluczem jest IRONFLOCK_API_KEY, gdy jest ustawiona, a w przeciwnym razie ten, który login zapisał dla instancji. Bez żadnego z nich polecenie kończy się kodem wyjścia 3 i podaje login do uruchomienia. Scopes to uprawnienia klucza, none, gdy nie ma żadnego. Restriction to none: everything the account may do, the projects 3, 5 lub the app 5. Z --json wynik ma instance, account_id, username, scopes, restriction, key_source (environment lub credential_file) oraz, dla zapisanego klucza, logged_in_at.
Zapisany klucz, którego instancja już nie przyjmuje, na przykład usunięty w Studio, nie jest usuwany: błąd podaje login, który go zastąpi.
ironflock logout
Usuwa zapisany klucz instancji. Loginy innych instancji pozostają.
ironflock logout [--instance <domain or URL>]$ ironflock logout --instance factory.example.com
Logged out of https://api.factory.example.com: its key is removed from /home/operator/.config/ironflock/credentials.json. The key itself stays valid until it is deleted in Studio.logout nie komunikuje się z żadną instancją: klucz pozostaje ważny, dopóki nie usuniesz go w Studio. Brak zapisanego loginu nie jest błędem: polecenie o tym informuje i kończy się kodem wyjścia 0. Gdy ustawiona jest IRONFLOCK_API_KEY, uwaga informuje, że polecenia nadal używają tej zmiennej.
ironflock device create
Tworzy urządzenie w projekcie i zapisuje plik .flock urządzenia, który zawiera poświadczenia urządzenia.
ironflock device create --project <project> --name <name> -o <file.flock> [flags]$ ironflock device create --project 12 --name press-7 -o press-7.flock
Created the device press-7 (key 345) in the project Packaging (key 12). Its .flock is in press-7.flock: it holds the device's credentials, which the platform shows no more. 'sudo ironflock agent install -c press-7.flock' connects a machine as this device.Działa w: Linuksie, macOS i Windows. Root: niepotrzebny. Wymaga: klucza z uprawnieniem devices:write; projekt podany po nazwie jest wyszukiwany z devices:read.
| Flaga | Znaczenie |
|---|---|
--project <project> | Wymagana. Klucz projektu albo jego nazwa |
--name <name> | Wymagana. Nazwa urządzenia: od 1 do 100 liter, cyfr, kropek, podkreślników i łączników. Projekt nie może mieć jeszcze urządzenia o tej nazwie |
-o, --output <file> | Wymagana. Plik na .flock, o nazwie *.flock, albo - dla standardowego wyjścia |
--description <text> | Najwyżej 2000 znaków |
--wifi-ssid <name> | Sieć Wi-Fi urządzenia. Występuje razem z --wifi-password-file |
--wifi-password-file <file> | Plik lub potok z hasłem sieci. Występuje razem z --wifi-ssid |
--force | Zastępuje plik z -o, gdy istnieje |
--instance, --ca-cert | Jak dla whoami |
- Projekt podany po nazwie jest wyszukiwany wśród projektów, w których klucz może pracować, i musi być dokładnie nazwą jednego projektu. Nazwa, która nie należy do żadnego, daje kod wyjścia 1. Nazwa, która należy do kilku projektów, daje kod wyjścia 2, a komunikat podaje ich klucze.
- Plik
.flockjest prywatny od pierwszego bajtu: tryb 0600 albo, w Windows, lista dostępu, która przyznaje dostęp tylko tobie. Istniejący plik nie jest zastępowany bez--force, a folder i nazwa są sprawdzane przed utworzeniem urządzenia, ponieważ API zwraca poświadczenia tylko przy tworzeniu urządzenia. W systemie plików bez trybów plików, takim jak pendrive sformatowany w FAT, plik nie jest prywatny: zapisz go na dysku maszyny i skopiuj stamtąd. -o -zapisuje plik na standardowe wyjście, które nie może być terminalem, na przykład aby przekazać go potokiem na inną maszynę. Wiersz wyniku trafia wtedy na standardowe wyjście błędów.- Nic z pliku nie jest wypisywane: wynik podaje urządzenie po kluczu i nazwie oraz projekt.
- Jeśli coś się nie powiedzie po utworzeniu urządzenia, błąd o tym mówi i podaje polecenie, które usuwa urządzenie.
Podłącz maszynę za pomocą tego pliku zgodnie z opisem w Polecenia agenta urządzenia albo zapisz go na nośniku przez os flash.
ironflock device list
Wyświetla urządzenia, do których twoje konto ma prawa, w projektach, w których klucz może działać.
ironflock device list [--project <project>] [--instance <instance>] [--ca-cert <file>]...$ ironflock device list --project Packaging
KEY NAME PROJECT STATUS ARCHITECTURE AGENT
17 press-7 12 CONNECTED amd64 1.4.2
18 press-8 12 CONFIGURING amd64 -Wymaga: klucza z uprawnieniem devices:read. --project zostawia urządzenia jednego projektu. Brak urządzeń nie jest błędem: polecenie mówi No devices. Z --json wynik ma instance i devices, każde urządzenie z device_key, name, project_key, description, status, architecture i agent_version. Z odpowiedzi odczytywane są tylko te pola: poświadczeń urządzenia nigdy wśród nich nie ma.
ironflock device delete
Usuwa urządzenie z projektu. Usuniętego urządzenia nie można przywrócić.
ironflock device delete --project <project> <device_key> [--yes] [--instance <instance>] [--ca-cert <file>]...$ ironflock device delete --project Packaging 17
This deletes the device 17 from the project Packaging (key 12) of https://api.ironflock.com. A deleted device cannot be brought back.
Delete the device 17? [y/N]
Deleted the device press-7 (key 17) from the project 12.Wymaga: klucza z uprawnieniem devices:write. Klucz urządzenia jest jedynym argumentem. Polecenie mówi, co zniknie, i pyta, z domyślnie zaznaczonym Nie; --yes odpowiada tak. Bez terminala i z --json o nic nie pyta i kończy się kodem wyjścia 4, chyba że podano --yes: wtedy nic nie jest usuwane. Urządzenie, którego nie ma w projekcie albo którego klucz nie widzi, daje 404.
Instalacja nowego urządzenia z --project i --name
ironflock agent install, ironflock os flash i ironflock os install przyjmują --project <project> --name <name> zamiast -c <device.flock>. Polecenie tworzy urządzenie i kontynuuje z .flock, który przysyła platforma, dokładnie tak, jak kontynuuje z plikiem z -c. .flock jest przechowywany w pamięci i w żadnym pliku, o który trzeba by dbać.
sudo ironflock agent install --project Packaging --name press-9 --yes
ironflock os flash --project 12 --name cell-4 -d /dev/sdb
ironflock --host admin@machine os install --project 12 --name cell-4 --disk /dev/sda --yes --wait-online| Flaga | Znaczenie |
|---|---|
--project <project> | Projekt, w którym ma powstać urządzenie: jego klucz lub nazwa, jak dla device create |
--name <name> | Nazwa nowego urządzenia, jak dla device create |
--instance <instance> | Instancja, jak dla whoami |
--ca-cert <file> | agent install: urząd certyfikacji certyfikatu instancji. os flash i os install mają własne --ca-cert, dla urządzenia; z --project jest ono zaufane także dla instancji |
--wait-online[=<duration>] | Tylko os install przez --host: po wykonaniu polecenia tam czeka do podanego czasu (od 1 minuty do 2 godzin; bez wartości 15 minut), aż platforma zobaczy urządzenie online. Wartość następuje po =, jak w --wait-online=20m |
--projecti--namewystępują razem i wykluczają-c.agent installios flashwymagają jednego z tych dwóch wariantów;os installbez żadnego używa.flockzainstalowanego agenta, jak dotąd.--dry-runz--projectjest odrzucane, ponieważ przebieg próbny niczego nie tworzy.- Kluczem jest ten z
whoami:IRONFLOCK_API_KEY, a w jej braku zapisany login. Polecenie uruchomione przezsudodziała jako root i szuka loginu roota: przekaż klucz przezsudo --preserve-env=IRONFLOCK_API_KEYalbo uruchom polecenie ze swojej maszyny z--host. Z--hostplatforma jest pytana z twojej maszyny, a maszyna dostaje tylko.flock: klucz, plik poświadczeń iIRONFLOCK_API_KEYnigdy do niej nie trafiają. - Platforma przekazuje
.flockurządzenia tylko w odpowiedzi, która je tworzy. Dlatego nazwa, którą projekt już ma, jest odrzucana (kod wyjścia 1): zainstaluj to urządzenie z jego.flocki-calbo najpierw usuń je przezdevice delete. - Jeśli krok nie powiedzie się po utworzeniu urządzenia, błąd o tym mówi i podaje polecenie
device delete, które usuwa urządzenie. Uruchom je, a potem ponownie to samo polecenie.
Błędy
Niepowodzenie kończy się kodem wyjścia 1 i zdaniem. Zdanie instancji następuje po statusie.
| Odpowiedź | Zdanie mówi |
|---|---|
| Brak połączenia, niezaufany certyfikat | Nie można dotrzeć do instancji, ze wskazówką dotyczącą --ca-cert |
400 | Instancja odrzuciła żądanie, i dlaczego |
401 | Instancja nie przyjmuje klucza, i skąd pochodził. Dla zapisanego klucza: login, który go zastąpi |
403 | Klucz nie może tego zrobić: nie pozwalają na to jego uprawnienia albo projekty lub aplikacja, do których jest ograniczony. whoami je pokazuje |
404 | Dla delete: urządzenia nie ma w projekcie albo klucz go nie widzi. Dla create: projekt nie istnieje dla tego klucza |
409 | Konflikt z tym, co przechowuje platforma, na przykład nazwa urządzenia, którą projekt już ma |
500, 503, 504 | Platforma jest niedostępna. Dla create i delete także to, że zmiana mogła zostać wykonana, oraz device list, które to pokaże |
Po każdym niepowodzeniu, które nastąpiło już po wysłaniu żądania, oraz po Ctrl-C, gdy create lub delete czeka, komunikat mówi, że zmiana mogła zostać wykonana. Zanim ją powtórzysz, uruchom ironflock device list: drugie create z tą samą nazwą to konflikt, a API nie zwraca ponownie poświadczeń pierwszego urządzenia (Studio może pobrać jego plik konfiguracyjny).
Kody wyjścia
Te polecenia używają kodów wyjścia wspólnych dla wszystkich poleceń.
| Kod | Znaczy tutaj |
|---|---|
| 0 | Gotowe |
| 1 | Instancja lub platforma odmówiła albo zawiodła, nazwa projektu nie należy do żadnego projektu albo nie udało się zapisać pliku |
| 2 | Wiersz poleceń jest błędny: brakująca lub błędna flaga, nazwa projektu należąca do kilku projektów, istniejący plik bez --force, --host lub --hosts. Platforma nie została zapytana |
| 3 | Brak loginu: IRONFLOCK_API_KEY nie jest ustawiona i żaden login nie jest zapisany; albo nie można użyć pliku poświadczeń. Platforma nie została zapytana |
| 4 | Na pytanie device delete odpowiedziano nie albo nie można było go zadać i nie podano --yes. Nic nie zostało usunięte |
| 130 | Przerwano w trakcie pytania platformy. Zmiana mogła zostać wykonana |