Skip to Content
Sviluppo App IoTIronFlock CLILogin e gestione dei dispositivi

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:

IndichiL’API è
niente, oppure ironflock.com, studio.ironflock.com o api.ironflock.comhttps://api.ironflock.com
il dominio dell’Appliance, factory.example.comhttps://api.factory.example.com
l’indirizzo con cui si apre Studio, https://factory.example.com/projects/12https://api.factory.example.com
l’host dell’API stessa, api.factory.example.comhttps://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.

VariabileSignificato
IRONFLOCK_INSTANCEL’istanza quando --instance non è indicato
IRONFLOCK_API_KEYLa chiave API da usare al posto di quella memorizzata
HTTPS_PROXY, NO_PROXYIl 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.

FlagSignificato
--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-9 e a-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 --json il risultato è un oggetto con action (logged_in), instance, account_id, username, scopes, restriction e credential_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.txt

Digita 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 UTC

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

FlagSignificato
--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
--forceSostituisce il file di -o quando esiste
--instance, --ca-certCome 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
FlagSignificato
--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
  • --project e --name vanno insieme ed escludono -c. agent install e os flash richiedono una delle due opzioni; os install senza nessuna delle due usa il .flock dell’agente installato, come prima. --dry-run con --project viene rifiutato, perché un’esecuzione di prova non crea nulla.
  • La chiave è quella di whoami: IRONFLOCK_API_KEY, altrimenti il login memorizzato. Un comando eseguito con sudo viene eseguito come root e cerca il login di root: passa la chiave con sudo --preserve-env=IRONFLOCK_API_KEY, oppure esegui il comando dalla tua macchina con --host. Con --host la piattaforma viene interrogata dalla tua macchina, e la macchina riceve solo il .flock: la chiave, il file delle credenziali e IRONFLOCK_API_KEY non la raggiungono mai.
  • La piattaforma fornisce il .flock di 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 .flock e -c, oppure eliminalo prima con device delete.
  • Se un passaggio fallisce dopo che il dispositivo è stato creato, l’errore lo dice e indica il comando device delete che 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.

RispostaLa frase dice
Non raggiunta, certificato non attendibileL’istanza non può essere raggiunta, con un suggerimento per --ca-cert
400L’istanza ha rifiutato la richiesta, e perché
401L’istanza non accetta la chiave, e da dove proviene. Per una chiave memorizzata, il login che la sostituisce
403La chiave non può farlo: le sue autorizzazioni, o i progetti o l’app a cui è limitata, non lo consentono. whoami li mostra
404Per delete: il dispositivo non è nel progetto, o la chiave non può vederlo. Per create: il progetto non esiste per questa chiave
409Un conflitto con ciò che la piattaforma contiene, come un nome di dispositivo che il progetto ha già
500, 503, 504La 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.

CodiceSignifica qui
0Fatto
1L’istanza o la piattaforma ha rifiutato o ha fallito, un nome di progetto non corrisponde a nessuno, o non è stato possibile scrivere un file
2La 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
3Nessun 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
4Alla domanda di device delete è stato risposto no, oppure non è stato possibile porla e --yes non era indicato. Non è stato eliminato nulla
130Interrotto mentre la piattaforma veniva interrogata. La modifica potrebbe essere stata eseguita
Last updated on