Login e gestione dei dispositivi
Questi comandi parlano con un’istanza IronFlock, il cloud o un Appliance, invece che con la macchina su cui vengono eseguiti. ironflock login memorizza una chiave API su questa macchina, whoami indica l’account a cui appartiene la chiave e logout rimuove la chiave. Poi ironflock device create, list e delete lavorano sui dispositivi dei tuoi progetti. agent install, os flash e os install possono creare il dispositivo per te con --project e --name.
Nessuno di essi richiede root, e tutti funzionano su Linux, macOS e Windows. Agiscono solo su questa macchina: --host e --hosts vengono rifiutati con il codice di uscita 2, e né la chiave né il file delle credenziali arrivano mai a un’altra macchina (Macchine remote via SSH).
login e whoami richiedono un’istanza il cui servizio API risponda a GET /v1/ironflock/whoami (Endpoint API). Il cloud IronFlock lo fa. Un’istanza senza quel percorso risponde 404, e i comandi lo dicono. Un IronFlock Appliance offre il percorso non appena esegue il servizio API IronFlock; le versioni dell’Appliance che non lo eseguono ancora non possono essere usate con questi comandi. I comandi parlano con l’API dell’istanza e con nient’altro, e usano il proxy dell’ambiente (HTTPS_PROXY, NO_PROXY) come ogni altra richiesta di ironflock.
L’istanza
Il cloud è il valore predefinito. --instance, o altrimenti la variabile d’ambiente IRONFLOCK_INSTANCE, indica un’altra istanza: un Appliance. Indica ciò che hai a portata di mano, e il comando ne ricava l’indirizzo dell’API:
| Indichi | L’API è |
|---|---|
niente, oppure ironflock.com, studio.ironflock.com o api.ironflock.com | https://api.ironflock.com |
il dominio dell’Appliance, factory.example.com | https://api.factory.example.com |
l’indirizzo con cui si apre Studio, https://factory.example.com/projects/12 | https://api.factory.example.com |
l’host dell’API stessa, api.factory.example.com | https://api.factory.example.com |
Senza schema, si intende https://. http in chiaro viene accettato solo per un indirizzo di loopback, per uno stack su questa macchina. Un indirizzo IP diverso dal loopback viene rifiutato: l’API di un Appliance si raggiunge tramite il suo nome. Un Appliance in modalità HTTP in chiaro non ha api.<domain>, e login non lo raggiunge. Il certificato dell’istanza viene verificato con l’archivio dei certificati attendibili di questa macchina e con le autorità di certificazione di --ca-cert (un file PEM, più volte per più autorità), ad esempio la CA della tua azienda che ha firmato il certificato di un Appliance. Niente disattiva la verifica.
Il file delle credenziali
login conserva la chiave in credentials.json nella cartella ironflock della cartella di configurazione del tuo utente: ~/.config/ironflock/ su Linux, ~/Library/Application Support/ironflock/ su un Mac e %LOCALAPPDATA%\ironflock\credentials\ su Windows. Contiene una voce per istanza ed è leggibile solo da te. Un file o una cartella che altri possono leggere o modificare non viene usato: il comando termina con il codice di uscita 3, dice come ripararlo e non modifica nulla.
Per script e CI, IRONFLOCK_API_KEY contiene una chiave che ogni comando usa al posto di quella memorizzata. login non la legge né la memorizza mai.
| Variabile | Significato |
|---|---|
IRONFLOCK_INSTANCE | L’istanza quando --instance non è indicato |
IRONFLOCK_API_KEY | La chiave API da usare al posto di quella memorizzata |
HTTPS_PROXY, NO_PROXY | Il proxy per le richieste all’istanza |
ironflock login
Memorizza una chiave API per un’istanza, dopo aver chiesto all’istanza a chi appartiene la chiave.
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.Funziona su: Linux, macOS e Windows. Root: non necessario. Chiede: nulla.
| Flag | Significato |
|---|---|
--key-file <file> | Il file o la pipe che contiene la chiave. Predefinito: lo standard input, quando non è un terminale |
--instance <instance> | L’istanza. Predefinito: IRONFLOCK_INSTANCE, altrimenti il cloud |
--ca-cert <file> | Un’autorità di certificazione da considerare attendibile oltre a quelle di questa macchina; più volte per più autorità |
- La chiave non va mai su una riga di comando. Arriva da un file o da una pipe, e il comando non la chiede mai al terminale. Senza nessuno dei due termina con il codice di uscita 2 e dice come passarla. Gli spazi attorno alla chiave vengono scartati. Una chiave è composta da 40 caratteri
0-9ea-f; qualsiasi altra cosa viene rifiutata prima di qualsiasi richiesta, e l’errore non la ripete. - Prima di memorizzare qualcosa, si chiede all’istanza a chi appartiene la chiave. Una chiave che l’istanza non accetta, un’istanza che non può rispondere, un certificato non attendibile o un’istanza non raggiungibile terminano con il codice di uscita 1, e ciò che era memorizzato prima resta com’era.
- Un login a un’istanza che ne ha già uno lo sostituisce. I login delle altre istanze restano.
- La richiesta non segue alcun reindirizzamento, così la chiave non va a nessun altro host.
- Con
--jsonil risultato è un oggetto conaction(logged_in),instance,account_id,username,scopes,restrictionecredential_file.
Metti la chiave in un file che solo tu puoi leggere, poi fai il login:
(umask 077; cat > key.txt)
ironflock login --key-file key.txtDigita o incolla la chiave nel terminale dopo cat > key.txt, termina con Ctrl-D ed elimina key.txt quando login ha memorizzato la chiave.
ironflock whoami
Indica l’account a cui appartiene la chiave e mostra cosa può fare la chiave.
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 UTCLa chiave è IRONFLOCK_API_KEY quando è impostata, altrimenti quella che login ha memorizzato per l’istanza. Senza nessuna delle due, il comando termina con il codice di uscita 3 e indica il login da eseguire. Scopes sono le autorizzazioni della chiave, none quando non ne ha. Restriction è none: everything the account may do, the projects 3, 5 o the app 5. Con --json il risultato ha instance, account_id, username, scopes, restriction, key_source (environment o credential_file) e, per una chiave memorizzata, logged_in_at.
Una chiave memorizzata che l’istanza non accetta più, ad esempio una eliminata in Studio, non viene rimossa: l’errore indica il login che la sostituisce.
ironflock logout
Rimuove la chiave memorizzata di un’istanza. I login delle altre istanze restano.
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 non parla con nessuna istanza: la chiave resta valida finché non la elimini in Studio. L’assenza di un login memorizzato non è un errore: il comando lo dice e termina con il codice di uscita 0. Con IRONFLOCK_API_KEY impostata, una nota dice che i comandi usano ancora la variabile.
ironflock device create
Crea un dispositivo in un progetto e scrive il file .flock del dispositivo, che contiene le sue credenziali.
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.Funziona su: Linux, macOS e Windows. Root: non necessario. Richiede: una chiave con l’autorizzazione devices:write; un progetto indicato per nome viene cercato con devices:read.
| Flag | Significato |
|---|---|
--project <project> | Obbligatorio. La chiave del progetto, o il suo nome |
--name <name> | Obbligatorio. Il nome del dispositivo: da 1 a 100 lettere, cifre, punti, underscore e trattini. Il progetto non deve avere ancora un dispositivo con quel nome |
-o, --output <file> | Obbligatorio. Il file per il .flock, con nome *.flock, oppure - per lo standard output |
--description <text> | Al massimo 2000 caratteri |
--wifi-ssid <name> | La rete Wi-Fi del dispositivo. Va insieme a --wifi-password-file |
--wifi-password-file <file> | Il file o la pipe con la passphrase della rete. Va insieme a --wifi-ssid |
--force | Sostituisce il file di -o quando esiste |
--instance, --ca-cert | Come per whoami |
- Un progetto indicato per nome viene cercato tra i progetti in cui la chiave può lavorare, e deve essere esattamente il nome di un progetto. Un nome che non corrisponde a nessuno dà il codice di uscita 1. Un nome che corrisponde a più progetti dà il codice di uscita 2, e il messaggio indica le loro chiavi.
- Il file
.flockè privato fin dal primo byte: modalità 0600, o su Windows una lista di accesso che concede l’accesso solo a te. Un file esistente non viene sostituito senza--force, e cartella e nome vengono verificati prima di creare il dispositivo, perché l’API restituisce le credenziali solo quando il dispositivo viene creato. Su un file system senza modalità dei file, come una chiavetta USB formattata FAT, il file non è privato: scrivilo su un disco della macchina e copialo da lì. -o -scrive il file sullo standard output, che non deve essere un terminale, ad esempio per inviarlo tramite pipe a un’altra macchina. La riga del risultato va allora sullo standard error.- Nulla del file viene stampato: il risultato indica il dispositivo per chiave e nome, e il progetto.
- Se qualcosa fallisce dopo che il dispositivo è stato creato, l’errore lo dice e indica il comando che elimina il dispositivo.
Collega una macchina con il file come descritto in Comandi dell’agente del dispositivo, oppure scrivilo su un’unità con os flash.
ironflock device list
Elenca i dispositivi su cui il tuo account ha diritti, tra i progetti in cui la chiave può agire.
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 -Richiede: una chiave con l’autorizzazione devices:read. --project mantiene solo i dispositivi di un progetto. L’assenza di dispositivi non è un errore: il comando dice No devices. Con --json il risultato ha instance e devices, ogni dispositivo con device_key, name, project_key, description, status, architecture e agent_version. Dalla risposta vengono letti solo questi campi: le credenziali di un dispositivo non sono mai tra questi.
ironflock device delete
Elimina un dispositivo da un progetto. Un dispositivo eliminato non può essere recuperato.
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.Richiede: una chiave con l’autorizzazione devices:write. La chiave del dispositivo è l’unico argomento. Il comando dice cosa viene eliminato e chiede conferma, con No preselezionato; --yes risponde sì. Senza un terminale, e con --json, non chiede nulla e termina con il codice di uscita 4 a meno che non sia indicato --yes: in quel caso non viene eliminato nulla. Un dispositivo che non è nel progetto, o che la chiave non può vedere, dà 404.
Installare un nuovo dispositivo con --project e --name
ironflock agent install, ironflock os flash e ironflock os install accettano --project <project> --name <name> al posto di -c <device.flock>. Il comando crea il dispositivo e prosegue con il .flock inviato dalla piattaforma, esattamente come prosegue con il file di -c. Il .flock resta in memoria e in nessun file di cui tu debba occuparti.
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| Flag | Significato |
|---|---|
--project <project> | Il progetto in cui creare il dispositivo: la sua chiave o il suo nome, come per device create |
--name <name> | Il nome del nuovo dispositivo, come per device create |
--instance <instance> | L’istanza, come per whoami |
--ca-cert <file> | agent install: un’autorità di certificazione del certificato dell’istanza. os flash e os install hanno un proprio --ca-cert, per il dispositivo; con --project viene considerato attendibile anche per l’istanza |
--wait-online[=<duration>] | Solo os install tramite --host: dopo il comando sulla macchina, attende fino alla durata indicata (da 1 minuto a 2 ore; senza valore 15 minuti) che la piattaforma veda il dispositivo online. Il valore segue =, come in --wait-online=20m |
--projecte--namevanno insieme ed escludono-c.agent installeos flashrichiedono una delle due opzioni;os installsenza nessuna delle due usa il.flockdell’agente installato, come prima.--dry-runcon--projectviene rifiutato, perché un’esecuzione di prova non crea nulla.- La chiave è quella di
whoami:IRONFLOCK_API_KEY, altrimenti il login memorizzato. Un comando eseguito consudoviene eseguito come root e cerca il login di root: passa la chiave consudo --preserve-env=IRONFLOCK_API_KEY, oppure esegui il comando dalla tua macchina con--host. Con--hostla piattaforma viene interrogata dalla tua macchina, e la macchina riceve solo il.flock: la chiave, il file delle credenziali eIRONFLOCK_API_KEYnon la raggiungono mai. - La piattaforma fornisce il
.flockdi un dispositivo solo nella risposta che lo crea. Un nome che il progetto ha già viene quindi rifiutato (codice di uscita 1): installa quel dispositivo con il suo.flocke-c, oppure eliminalo prima condevice delete. - Se un passaggio fallisce dopo che il dispositivo è stato creato, l’errore lo dice e indica il comando
device deleteche rimuove il dispositivo. Eseguilo, poi esegui di nuovo lo stesso comando.
Errori
Un errore termina con il codice di uscita 1 e una frase. La frase dell’istanza segue lo stato.
| Risposta | La frase dice |
|---|---|
| Non raggiunta, certificato non attendibile | L’istanza non può essere raggiunta, con un suggerimento per --ca-cert |
400 | L’istanza ha rifiutato la richiesta, e perché |
401 | L’istanza non accetta la chiave, e da dove proviene. Per una chiave memorizzata, il login che la sostituisce |
403 | La chiave non può farlo: le sue autorizzazioni, o i progetti o l’app a cui è limitata, non lo consentono. whoami li mostra |
404 | Per delete: il dispositivo non è nel progetto, o la chiave non può vederlo. Per create: il progetto non esiste per questa chiave |
409 | Un conflitto con ciò che la piattaforma contiene, come un nome di dispositivo che il progetto ha già |
500, 503, 504 | La piattaforma non è disponibile. Per create e delete, anche che la modifica potrebbe essere stata eseguita, e il device list che lo mostra |
Dopo qualsiasi errore avvenuto una volta scritta la richiesta, e dopo Ctrl-C mentre create o delete attende, il messaggio dice che la modifica potrebbe essere stata eseguita. Esegui ironflock device list prima di ripeterla: un secondo create con lo stesso nome è un conflitto, e l’API non restituisce di nuovo le credenziali del primo dispositivo (Studio può scaricarne il file di configurazione).
Codici di uscita
Questi comandi usano i codici di uscita di ogni comando.
| Codice | Significa qui |
|---|---|
| 0 | Fatto |
| 1 | L’istanza o la piattaforma ha rifiutato o ha fallito, un nome di progetto non corrisponde a nessuno, o non è stato possibile scrivere un file |
| 2 | La riga di comando è errata: un flag mancante o errato, un nome di progetto che corrisponde a più progetti, un file esistente senza --force, --host o --hosts. La piattaforma non è stata interrogata |
| 3 | Nessun login: IRONFLOCK_API_KEY non è impostata e non ne è memorizzato nessuno; oppure il file delle credenziali non può essere usato. La piattaforma non è stata interrogata |
| 4 | Alla domanda di device delete è stato risposto no, oppure non è stato possibile porla e --yes non era indicato. Non è stato eliminato nulla |
| 130 | Interrotto mentre la piattaforma veniva interrogata. La modifica potrebbe essere stata eseguita |