Comandi dell’agente del dispositivo

I comandi ironflock agent collegano una macchina Linux a IronFlock come dispositivo e da quel momento si occupano dell’agente del dispositivo. Li usi per installare l’agente, per dargli un’altra configurazione del dispositivo o un altro proxy, per aggiornarlo, arrestarlo e avviarlo, per leggerne il log e per rimuoverlo di nuovo.

L’agente del dispositivo

L’agente del dispositivo è il programma che collega una macchina a IronFlock come dispositivo ed esegue in Docker le app del progetto del dispositivo. Quale dispositivo diventa una macchina lo stabilisce il file di configurazione del dispositivo (.flock) che IronFlock Studio fornisce per ciascun dispositivo (Connettere i Dispositivi).

Ogni comando dell’agente richiede root e funziona su Linux. Senza root termina con il codice di uscita 3 e non chiama sudo da solo (Privilegi di root). Su macOS i comandi dell’agente terminano con il codice di uscita 3 prima di esaminare qualsiasi cosa; eseguili sulla macchina Linux, oppure dal Mac con --host. Su un dispositivo IronFlockOS l’immagine porta con sé l’agente insieme al sistema: lì agent install e agent remove rifiutano, e agent configure -c registra il dispositivo con un altro .flock.

Ogni comando accetta anche i flag globali --yes, --json, --download-base, --host, --hosts e --parallel (Flag globali). Una domanda richiede un terminale; senza terminale, indica --yes (Domande e conferma).

Con --host, un comando viene eseguito su un’altra macchina via SSH (Macchine remote via SSH). Su più macchine contemporaneamente (--host più volte, oppure --hosts), agent restart, agent start e agent logs vengono eseguiti così come sono, ma agent logs --follow non con --json. Lì agent stop, agent update, agent configure e agent remove richiedono --yes, perché non viene chiesto nulla a nessuno, e agent configure non accetta -c, perché un .flock indica un solo dispositivo. agent install viene eseguito su una macchina alla volta.

Com’è fatto un agente installato

L’agente scrive anche da sé alcune impostazioni dell’host, a ogni avvio: la slice ironflock.slice in cui viene eseguito, che gli riserva memoria, il watchdog di systemd, le impostazioni del kernel per i crash e un limite alla dimensione del journal.

Una macchina configurata da un installer IronFlock precedente può avere ancora l’agente nella struttura legacy /opt/reagent (servizio reagent.service, log /var/log/reagent.log), che l’agente sposta da sé in /opt/ironflock/device-agent; ironflock status mostra quale struttura ha una macchina, e i rifiuti descritti più avanti indicano i casi in cui conta.

ironflock agent install

Installa l’agente del dispositivo in /opt/ironflock/device-agent, Docker quando manca e le impostazioni predefinite dell’host di un dispositivo, e collega la macchina a IronFlock come il dispositivo del .flock. L’agente si avvia subito e da quel momento si aggiorna da solo.

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

Funziona su: Linux basato su Debian o Ubuntu, con systemd; non su IronFlockOS. Root: richiesto. Chiede: prima di installare i pacchetti e Docker, e per ogni impostazione predefinita dell’host; --yes risponde a ogni domanda con il valore predefinito.

La macchina richiede l’accesso a internet, oppure al server di download indicato con --download-base (Base di download), oppure al mirror di download dell’Appliance indicato dal .flock (Da dove viene l’agente). Gli host che un dispositivo deve raggiungere sono elencati in Requisiti di Rete.

Da dove viene l’agente

L’agente è composto dalla sua mappa dei canali, dal suo binario e dai file .sha256 e .sig del binario. Il comando li prende da:

1. --download-base, altrimenti IRONFLOCK_DL_BASE: solo da quel server.
2. Altrimenti dal mirror di download dell’IronFlock Appliance che il .flock indica come suo server di aggiornamento (update_url), quando il suo host non è uno del cloud IronFlock. Così si installa una macchina che raggiunge l’Appliance ma non ironflock.com. Un .flock del cloud IronFlock usa il cloud.
3. Altrimenti dal cloud IronFlock, https://instance-registry.ironflock.com/dl.

Il comando indica la base su stderr: Download base: ... (from the device's .flock), altrimenti (from --download-base), (from IRONFLOCK_DL_BASE) o (from default).

Con il mirror dell’Appliance, i file vengono prima dal mirror e, quando il mirror non li fornisce, dallo stesso percorso sotto la base di download del cloud IronFlock:

• La mappa dei canali — quando il mirror al momento non ne fornisce una (nessuna risposta, nessuna mappa, uno stato di errore), tutto viene dal cloud, e la versione è quella indicata dalla mappa del cloud. Una mappa fornita dal mirror ma rifiutata (la sua firma, nessuna versione) fa fallire l’installazione, come da qualsiasi server.
• Il binario, il suo .sha256 e il suo .sig — ognuno di questi file che il mirror non fornisce viene dal cloud. Quando i file del mirror non superano i controlli (checksum, firma), tutti e tre vengono dal cloud.

Ogni ripiego è una riga Warning: ... su stderr, con il mirror, il file e il motivo, e con --json una voce di warnings nel risultato. Quando né il mirror né il cloud forniscono un file, l’installazione fallisce con un unico errore che indica entrambe le fonti ed entrambi i motivi (neither the appliance's mirror ... nor the IronFlock cloud gives ...).

Il mirror è il server di aggiornamento del .flock, che aggira il proxy (Proxy). Un mirror HTTPS con un certificato della CA propria dell’Appliance funziona solo dove il sistema della macchina considera attendibile quella CA. I pacchetti della distribuzione e Docker continuano a venire dai loro server, e install.sh e ironflock da ironflock.com; con --host, ironflock passa dal tuo computer alla macchina.

Controlli prima dell’installazione

Prima di modificare qualsiasi cosa, il comando esegue i controlli di ironflock doctor che dicono se può riuscire: system, systemd, disk_space, clock, dns, proxy, download_tree, device_endpoint, docker_registry e update_server. Vengono eseguiti per il .flock di -c, con la base di download e i flag del proxy dell’installazione.

Quattro di essi fermano l’installazione quando falliscono, perché l’installazione fallirebbe di sicuro, oppure a metà:

Il messaggio indica il controllo, il suo riscontro e il suo suggerimento. Ogni altro riscontro è un avviso su stderr, e l’installazione prosegue: l’agente si connette, si aggiorna e scarica le sue app non appena la rete lo consente. Un risultato warning o skipped non ferma mai l’installazione. Esegui ironflock doctor -c device.flock per vedere ogni controllo prima di installare.

Passi

1. Indica i pacchetti che installa e chiede. Li installa con apt.
2. Installa Docker quando la macchina non lo ha, e prima chiede.
3. Scarica l’agente del canale di produzione e lo verifica rispetto al suo checksum e alla sua firma. Un’installazione che non riesce a ottenere un agente verificato si ferma qui, prima di tutti i passi seguenti.
4. Configura Docker: il proxy, quando ne è indicato uno, e, per un Docker portato da questa installazione o che non contiene ancora nulla, la data-root nella cartella dell’agente. Un Docker che contiene immagini o container mantiene la sua configurazione e i suoi dati.
5. Configura le impostazioni predefinite dell’host (tabella qui sotto). Ognuna è una scelta al terminale; --yes prende il valore predefinito.
6. Installa l’agente in /opt/ironflock/device-agent e lo avvia.

L’installazione aggiunge anche un banner di accesso. Tutto ciò che l’installazione modifica viene scritto in /opt/ironflock/device-init/installed.json. Quando fallisce un passo dal passo 4 in poi, l’errore dice che il tentativo è stato annotato e che lo stesso comando, eseguito di nuovo, prima lo annulla. Quando il comando trova un tentativo precedente di questo tipo, lo annulla dopo che i controlli sono stati superati: elenca ciò che annulla, chiede, e poi installa di nuovo.

Proxy

I flag del proxy impostano il proxy aziendale per i download dell’installazione, per Docker e per l’agente. Ogni impostazione viene dal suo flag, altrimenti dalle variabili d’ambiente HTTP_PROXY, HTTPS_PROXY e NO_PROXY (o dalle loro forme in minuscolo).

Un URL di proxy ha la forma http://proxy.example.com:3128; funzionano anche https:// e socks5://, e un URL senza schema vale come http://. Quando il proxy richiede un login, l’URL indica l’utente senza la password, http://[email protected]:3128, e --proxy-password-file fornisce la password. Il comando inserisce la password negli URL dei flag che indicano un utente.

Avviso: Non scrivere mai la password del proxy nell’URL. Le righe di comando compaiono in ps e nella cronologia della shell, quindi un URL con una password viene rifiutato come riga di comando errata, e l’errore non la ripete. Scrivi la password su una riga di un file, oppure passala tramite una pipe con --proxy-password-file /dev/stdin (Segreti).

Oltre agli host di --no-proxy, aggirano il proxy (NO_PROXY): localhost, 127.0.0.1 e ::1, e il server di download e il server di aggiornamento del .flock (il suo update_url) quando non sono host del cloud IronFlock, come un Appliance o un mirror nella LAN. Gli host del cloud IronFlock (ironflock.com, ironflock.dev e gli host sotto di essi, e storage.googleapis.com) si trovano su internet e passano attraverso il proxy.

L’installazione scrive il proxy di Docker e dell’agente in /etc/ironflock/proxy.env, che solo root legge (modo 0600), e Docker si riavvia per usarlo. I drop-in systemd ironflock-proxy.conf di docker.service e di ironflock-device-agent.service indicano quel file e non contengono impostazioni proprie, quindi systemctl show rivela a ogni utente il nome del file e nulla del suo contenuto. Un drop-in di Docker proprio dell’host (docker.service.d/http-proxy.conf) resta; le impostazioni di IronFlock hanno la precedenza sulle sue righe Environment=, e un avviso lo indica. Un daemon.json con proxies li mantiene, perché per Docker hanno la precedenza su qualsiasi altra impostazione.

Per modificare le impostazioni in seguito, usa agent configure. Per il proxy dell’intera sede, vedi Dietro un Proxy Aziendale.

Esempi

# Installa l'agente; il comando chiede prima di ogni passo
sudo ironflock agent install -c device.flock
# Installa senza domande e impedisci al dispositivo di andare in sospensione
sudo ironflock agent install -c device.flock --yes --disable-suspend
# Installa dietro un proxy che non richiede login
sudo ironflock agent install -c device.flock --https-proxy http://proxy.example.com:3128
# Installa dietro un proxy con login; la password viene da un file
sudo ironflock agent install -c device.flock --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt

Risultato

$ 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 compare nel risultato solo quando un file è venuto dal cloud IronFlock invece che dal mirror dell’Appliance: una voce per ciascuno, come la indicano le righe Warning:.

Quando rifiuta

Una riga di comando errata termina con il codice di uscita 2 prima di eseguire qualsiasi cosa: un URL di proxy con una password; un URL di proxy che indica un utente, senza --proxy-password-file; --proxy-password-file senza un URL di proxy che indichi un utente; un valore che non è un URL di proxy. Conta anche una variabile proxy dell’ambiente che non è un URL di proxy; l’errore indica la variabile, non il suo valore.

Il comando rifiuta con il codice di uscita 3, e non modifica nulla, quando:

• non viene eseguito come root, o la macchina non è Linux;
• la macchina esegue IronFlockOS, prima di ogni altra cosa, come root o no. L’immagine porta con sé l’agente e ironflock insieme al sistema, e ogni aggiornamento del sistema operativo sostituisce il sistema nel suo insieme. Il messaggio dice che il dispositivo si registra con un .flock sulla sua partizione IRONFLOCKOS al prossimo avvio, e che agent configure -c lo registra subito. Sulla chiavetta di installazione di IronFlockOS dice che la chiavetta non è un dispositivo;
• è già installato un agente, anche nella struttura legacy /opt/reagent. Il messaggio indica agent configure e agent remove;
• l’agente sta spostando la macchina dalla struttura legacy a quella attuale;
• un’installazione precedente si è fermata prima che l’agente fosse configurato, aveva spostato la data-root di Docker, e da allora Docker contiene immagini o container: annullare quel tentativo li cancellerebbe;
• uno dei controlli system, systemd, disk_space o download_tree fallisce. --yes non cambia nulla.

Una domanda a cui è stato risposto no, o una domanda senza terminale e senza --yes, termina il comando con il codice di uscita 4. Un passo che fallisce lo termina con il codice di uscita 1.

ironflock agent configure

Modifica ciò che l’installazione ha configurato: il .flock del dispositivo, il proxy aziendale di Docker e dell’agente, o entrambi. Riavvia ciò che deve usare la modifica.

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

Funziona su: Linux con un agente installato; su IronFlockOS solo con -c. Root: richiesto. Chiede: prima che Docker si riavvii per nuove impostazioni del proxy; --yes risponde.

Indica -c, un flag del proxy, o entrambi. Senza nessuno dei due non c’è nulla da modificare: è una riga di comando errata (codice di uscita 2).

Un altro .flock

Con -c, l’agente riceve il .flock indicato e si riavvia: la macchina diventa il dispositivo di quel .flock. Le app e i loro dati restano. Quando l’installazione ha configurato un utente SSH, l’utente SSH segue il .flock:

• Stesso proprietario del progetto, altra chiave del dispositivo — la vecchia chiave non viene più accettata, la nuova sì.
• Un altro proprietario del progetto — il nuovo proprietario riceve il suo utente SSH, e l’utente SSH del primo proprietario viene rimosso come lo rimuove agent remove: la regola sudo, la chiave e l’account con la sua cartella home, se l’ha creato l’installazione.
• Un .flock senza chiave del dispositivo — l’utente SSH viene rimosso e non ne arriva nessuno.

Quando il dispositivo cambia proprietario, chi esegue il comando può essere proprio il primo proprietario, via SSH con lo stesso account che viene rimosso, e la rimozione di un account ne termina le sessioni. Per questo il comando procede in questo ordine: configura l’account del nuovo proprietario (utente, chiave, regola sudo), riavvia l’agente con il nuovo .flock, e solo allora toglie la regola sudo, le sessioni e l’account del primo proprietario (o soltanto la vecchia chiave, per lo stesso proprietario). Il dispositivo ha un nuovo accesso, ed è online, prima che quello vecchio venga rimosso. Prima che le sessioni terminino, una riga su stderr lo dice, ad esempio Removing the account anna, ...: a session of anna ends here.

• Quando l’agente non si riavvia con il nuovo .flock, il primo proprietario mantiene l’accesso: qualcuno deve poter entrare.
• Quando è fallito solo l’utente SSH del nuovo proprietario, l’accesso del primo proprietario viene rimosso comunque: il dispositivo ha cambiato proprietario ed è online.
• Gli accessi ancora da rimuovere sono annotati in /opt/ironflock/device-init/installed.json (users_to_remove). Ogni successivo agent configure -c e agent remove ci riprova.
• Un account che il nuovo .flock configura di nuovo non viene mai rimosso (proprietario A, poi B, poi di nuovo A).
• Dalla sua prima modifica in poi, un terminale o una sessione SSH persi non fermano il comando.

Via --host, la copia del .flock sulla macchina viene rimossa non appena il comando l’ha letta. Quando l’utente di login di --host è un account che viene rimosso, la sessione SSH termina con l’account: la tua esecuzione termina allora con il codice di uscita 255, come dopo una connessione persa, e il comando sulla macchina prosegue fino alla fine. La cartella dell’esecuzione ironflock.XXXXXXXXXX con il suo binario resta allora sulla macchina; in una cartella temporanea resta finché questa non viene ripulita, nella home dell’account viene rimossa con l’account.

Su IronFlockOS

Con -c, il comando registra il dispositivo come lo registra IronFlockOS al primo boot di ogni nuovo slot di root, sia su un dispositivo che si è già registrato sia su uno che non lo ha ancora fatto. Il .flock indicato diventa la copia dell’agente, /opt/ironflock/device-agent/device-config.flock su /data, e il dispositivo viene configurato a partire da esso in questo ordine: l’utente SSH del proprietario del progetto, il WiFi, il nome host dal nome del dispositivo (salvo che /etc/ironflockos/enroll.conf indichi hostname-from-flock=no), l’agente, riavviato con il nuovo .flock, e infine la rimozione dell’accesso del proprietario precedente.

Il prossimo aggiornamento del sistema operativo registra il suo nuovo slot di root dalla stessa copia. Il file che hai indicato resta dov’è. Un passo che fallisce non impedisce all’agente di riavviarsi con il nuovo .flock, ma l’accesso del primo proprietario viene rimosso solo dopo che l’agente si è riavviato. Il comando termina allora con il codice di uscita 1 e indica ogni passo fallito; esegui di nuovo lo stesso comando per ripeterli.

I flag del proxy vengono rifiutati su IronFlockOS. IronFlockOS tiene il proxy per Docker, per l’agente e per il proprio orologio in /etc/ironflockos/proxy.conf su /data, e un proxy.conf sulla sua partizione IRONFLOCKOS lo sostituisce al prossimo avvio.

Impostazioni del proxy

• Ogni flag del proxy indicato sostituisce la sua impostazione, e le altre restano. --https-proxy da solo cambia il proxy HTTPS e mantiene il proxy HTTP e gli host che aggirano i due proxy.
• La password di --proxy-password-file va negli URL passati che indicano un utente. Senza URL passati, va negli URL delle impostazioni del dispositivo che ne indicano uno, quindi una nuova password si imposta con il solo file.
• --no-proxy, e il primo proxy di un dispositivo che non ne aveva, aggiungono anche localhost, 127.0.0.1, ::1 e il server di aggiornamento del .flock dell’agente quando non è un host del cloud IronFlock (quello di un Appliance).
• --remove-proxy rimuove le impostazioni. Non accetta altri flag del proxy.
• Le variabili proxy del tuo ambiente qui non cambiano nulla: contano solo i flag.

L’elenco degli host che aggirano il proxy resta come il comando lo trova, a meno che --no-proxy non ne indichi un altro. Quando quell’elenco contiene un host del cloud IronFlock, un avviso lo indica, con il comando agent configure --no-proxy che imposta l’elenco senza di esso. Un dispositivo che raggiunge internet solo tramite il proxy non può aggiornare il suo agente finché il server di download del cloud, instance-registry.ironflock.com, si trova in quell’elenco.

Le impostazioni sono conservate in /etc/ironflock/proxy.env, che solo root legge, e indicate dai drop-in ironflock-proxy.conf di docker.service e ironflock-device-agent.service. Quando le impostazioni cambiano, il comando le mostra prima e dopo, senza la password. Poi Docker e l’agente si riavviano. Il riavvio di Docker arresta per un momento le app del dispositivo, quindi il comando lo dice e chiede; --yes risponde. Con la password su stdin non c’è un terminale su cui chiedere: indica --yes.

• Docker non si riavvia, e non viene chiesto nulla, quando il daemon.json di Docker imposta proxies (per Docker hanno la precedenza su queste impostazioni) e quando non cambia nulla.
• Una unit a cui manca solo il suo drop-in lo riceve, e si riavvia solo quella unit.
• Un drop-in di Docker proprio dell’host resta com’è. Un altro drop-in dell’agente, o di Docker, che imposta una variabile proxy viene indicato in un avviso; le impostazioni di IronFlock lo sovrascrivono per ogni variabile che impostano. Anche un drop-in o un daemon.json che contiene una password del proxy leggibile da ogni utente viene indicato in un avviso.
• Quando il riavvio di Docker fallisce, l’agente si riavvia comunque, e viceversa. L’errore (codice di uscita 1) indica le unit ancora in esecuzione con le vecchie impostazioni e il systemctl restart che le applica; una seconda esecuzione trova le impostazioni al loro posto e non riavvia nulla.
• Quando non è possibile scrivere le impostazioni, non si riavvia nulla, e l’errore dice di eseguire di nuovo il comando.

Le impostazioni del proxy che una vecchia installazione ha scritto nelle righe Environment= dei drop-in http-proxy.conf, dove ogni utente può leggerle con systemctl show, password compresa, passano in /etc/ironflock/proxy.env con qualsiasi esecuzione di agent configure, anche una con il solo -c. Dei vecchi file non viene conservata alcuna copia. Di regola lo spostamento mantiene i valori, quindi non riavvia nulla e non chiede nulla; dove cambia il proxy usato da una unit, il comando dice perché, mostra il proxy di quella unit prima e dopo, e chiede. Un valore che il file delle impostazioni non può contenere (un apice singolo nell’host o nell’elenco degli host che aggirano il proxy, un carattere di controllo) non viene spostato: un’esecuzione senza flag del proxy lo lascia, dà un avviso e indica il flag che reimposta il valore.

Esempi

# Rendi questa macchina il dispositivo di un altro .flock
sudo ironflock agent configure -c new-device.flock
# Imposta un proxy HTTPS con login; la password viene da un file
sudo ironflock agent configure --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt
# Imposta solo una nuova password del proxy, letta da stdin, senza domande
sudo ironflock agent configure --proxy-password-file /dev/stdin --yes < proxy-password.txt
# Rimuovi le impostazioni del proxy: Docker e l'agente si connettono direttamente
sudo ironflock agent configure --remove-proxy

Risultato

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

Su IronFlockOS, -c riporta la registrazione:

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

Quando rifiuta

Una riga di comando errata termina con il codice di uscita 2: nulla da modificare; --remove-proxy con un altro flag del proxy; un URL di proxy con una password; un URL di proxy che indica un utente, senza --proxy-password-file; --proxy-password-file con URL di cui nessuno indica un utente; un valore che non è un URL di proxy o un elenco di host.

Il comando rifiuta con il codice di uscita 3, e non modifica nulla, quando:

• non è installato alcun agente (il messaggio indica agent install), tranne su IronFlockOS, dove -c registra un dispositivo che non si è ancora registrato;
• l’agente sta spostando la macchina dalla struttura legacy a quella attuale;
• sono indicati flag del proxy e l’agente è ancora in esecuzione nella struttura legacy /opt/reagent. Dopo che l’agente ha spostato la macchina (ironflock status mostra la struttura), lo stesso comando funziona;
• sono indicati flag del proxy su IronFlockOS, con -c o senza;
• --no-proxy o --proxy-password-file è indicato da solo su un dispositivo senza proxy, oppure il file della password da solo quando nessun URL di proxy del dispositivo indica un utente;
• i flag del proxy mantengono un valore della vecchia forma che /etc/ironflock/proxy.env non può contenere; il messaggio indica il flag che lo reimposta.

Su IronFlockOS, -c viene rifiutato con il codice di uscita 3 quando la registrazione non conserverebbe il .flock:

• è stato richiesto un reset di fabbrica che non è ancora iniziato (/boot/efi/factory-reset.conf, che os reset scrive), oppure è già iniziato (/boot/efi/factory-reset.keep): il prossimo avvio cancellerebbe ciò che il comando configura;
• un reset di fabbrica è aperto o ha rinunciato e trattiene i file arrivati con esso (/run/ironflockos/factory-reset-hold; ironflock status dice di più);
• non è stato possibile montare /data, quindi la copia dell’agente finirebbe nello slot di root. In quel caso la strada è un .flock sulla partizione IRONFLOCKOS;
• sulla partizione IRONFLOCKOS si trova un .flock; il dispositivo si registra con esso al prossimo avvio, e il messaggio lo indica;
• il comando viene eseguito sulla chiavetta di installazione di IronFlockOS, che non è un dispositivo;
• il sistema non ha /usr/lib/ironflock/image.json, oppure ha un agente nella struttura legacy.

ironflock agent update

Fa aggiornare l’agente da solo alla release del suo canale e segue ciò che fa. L’agente cerca una release più recente a ogni avvio: il comando lo riavvia e riferisce l’esito. Il dispositivo è offline in IronFlock per un momento; le sue app continuano a funzionare.

ironflock agent update [flags]

Funziona su: Linux, con un agente installato. Root: richiesto. Chiede: sì, dopo aver detto cosa comporta il riavvio; --yes risponde.

Il comando non ha flag propri e non accetta una versione. L’agente segue il suo canale (production, o test sulla piattaforma di test di IronFlock), dal suo server di aggiornamento: l’update_url del suo .flock (il mirror di un Appliance), altrimenti il cloud IronFlock. --download-base non lo cambia.

Cosa fa l’agente, in questo ordine:

1. Legge la release del suo canale. Una release che è fallita due volte su questo dispositivo non viene scaricata di nuovo finché non ne esce una più recente.
2. Scarica una release più recente nella sua cartella e ne verifica la firma.
3. Mette al suo posto la nuova versione e si riavvia con essa, 10 secondi dopo il download. Rimanda l’aggiornamento quando la sua ultima connessione a IronFlock risale a un momento compreso tra 12 minuti e un giorno prima: un aggiornamento si attiva solo da una versione di cui si sa che si connette.
4. La nuova versione è in prova: deve connettersi a IronFlock entro 10 minuti dal suo avvio e restare attiva per 2 minuti. Se non lo fa, o si arresta tre volte prima, l’agente torna alla versione precedente.
5. Dopo un rollback, la versione precedente deve connettersi. Se lo fa, la colpa era della nuova versione: viene riprovata una volta al prossimo aggiornamento, e dopo il suo secondo fallimento viene bloccata fino a una release più recente. Quando nemmeno la versione precedente riesce a connettersi entro 10 minuti, l’agente attribuisce la colpa alla rete, e la nuova versione viene riprovata al prossimo aggiornamento.

Il comando segue tutto questo in update-state.json nella cartella dell’agente e nel log dell’agente; di nessuno dei due legge ciò che precede il riavvio. Il suo avanzamento va su stderr come righe di testo, anche con --json. Un download mostra una volta al minuto quanto ha scaricato finora.

Con il codice di uscita 1 il risultato viene scritto comunque, e stderr riceve la riga Error:. Con --json non segue alcun oggetto errore: stdout contiene il risultato.

Esempi

# Aggiorna l'agente; il comando chiede prima del riavvio
sudo ironflock agent update
# Aggiorna senza domande e leggi l'esito come JSON
sudo ironflock agent update --yes --json

Risultato

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

Un agente già aggiornato, e uno la cui nuova versione è finita in rollback:

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

Quando rifiuta

Il comando rifiuta con il codice di uscita 3 quando non è installato alcun agente (il messaggio indica agent install), mentre l’agente sposta la macchina dalla struttura legacy a quella attuale, quando l’agente è in esecuzione nella struttura legacy (i suoi aggiornamenti non conservano uno stato che il comando possa seguire), e con un agente più vecchio della 1.3.0, la prima versione che si aggiorna da sola sotto la propria unit.

Fallisce con il codice di uscita 1, e un errore che dice dove guardare, quando il riavvio fallisce e quando l’aggiornamento non avanza entro i tempi dell’agente: il controllo dell’agente entro 3 minuti dal riavvio, il download entro 30 minuti, l’attivazione entro 3 minuti, ogni avvio della nuova versione in prova entro 12 minuti, il verdetto dell’agente dopo un rollback entro 12 minuti, e tutto quanto entro 84 minuti. L’agente prosegue da solo; ironflock status mostra a che punto è.

Ctrl-C smette di seguire l’aggiornamento, senza fermarlo, e termina il comando con il codice di uscita 130.

ironflock agent remove

Rimuove l’agente del dispositivo e annulla ciò che la sua installazione ha annotato. Docker stesso e i pacchetti restano installati.

ironflock agent remove [flags]

Funziona su: Linux, con un agente installato; non su IronFlockOS. Root: richiesto. Chiede: sì, dopo aver elencato ciò che rimuove. La domanda ha «No» preselezionato: Invio da solo non rimuove nulla.

Il comando non ha flag propri. Rimuove:

• L’agente — l’agente, il suo database e /opt/ironflock/device-agent. Le app del dispositivo e i loro dati vengono rimossi con esso quando Docker li tiene nella cartella dell’agente.
• L’utente SSH — l’account solo se l’ha creato l’installazione. Di un account che esisteva già, viene tolta solo la chiave del dispositivo dal suo authorized_keys, che resta all’utente. Viene rimosso anche l’accesso di un precedente proprietario del progetto la cui rimozione da parte di agent configure -c era fallita, elencato con «(a removal that had failed)».
• Le impostazioni predefinite dell’host — il profilo WiFi, il banner di accesso e i target di sospensione mascherati.
• I file che l’installazione ha scritto o sostituito — tornano gli originali, con il loro modo, proprietario e gruppo.
• Le impostazioni del proxy — /etc/ironflock/proxy.env con i drop-in che lo indicano, e le impostazioni del proxy che una vecchia installazione ha lasciato nei drop-in http-proxy.conf. Al loro posto non torna nulla: dopo, Docker non ha alcun proxy da IronFlock, e il comando non ha scritto la password del proxy da nessuna parte. Quando Docker aveva un proxy da IronFlock, l’elenco prima della domanda lo dice.
• Le impostazioni che l’agente ha scritto da sé sull’host — la slice ironflock.slice con il drop-in 10-ironflock-resources.conf della sua unit, il watchdog di systemd (/etc/systemd/system.conf.d/10-ironflock-watchdog.conf), le impostazioni del kernel per i crash (/etc/sysctl.d/60-ironflock-crash-recovery.conf, che il kernel mantiene fino al prossimo boot) e il limite del journal (/etc/systemd/journald.conf.d/10-ironflock.conf).
• I login dell’agente ai registry — dopo che l’agente si è arrestato, il comando esegue docker logout per il registry indicato dal .flock (docker_registry_url) e, su un dispositivo di un Appliance, per registry.<appliance_domain>. Nessun altro login in /root/.docker/config.json viene toccato. Un Docker che manca o fallisce non ferma la rimozione; una riga dice quale login non è stato rimosso.

Un drop-in di Docker proprio dell’host resta com’è. Un Docker che non si riavvia per la rimozione (i suoi dati non erano nella cartella dell’agente) usa il proxy con cui si è avviato fino al suo prossimo riavvio.

Il comando elenca su stderr ciò che rimuove, poi chiede. Con --json l’elenco è il campo removed del risultato. Una volta che il comando ha iniziato a rimuovere, un terminale o una sessione SSH persi non lo fermano: l’utente SSH rimosso porta con sé le sue sessioni, forse anche quella che esegue il comando, e la rimozione prosegue fino alla fine.

Esempi

# Rimuovi l'agente; il comando elenca ciò che viene rimosso e chiede
sudo ironflock agent remove
# Rimuovi l'agente senza domande
sudo ironflock agent remove --yes

Risultato

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

Quando rifiuta

Il comando rifiuta con il codice di uscita 3 quando non è installato alcun agente, e mentre l’agente sposta la macchina dalla struttura legacy a quella attuale. Su IronFlockOS rifiuta prima di ogni altra cosa, come root o no: l’immagine porta con sé l’agente insieme al sistema, e ogni aggiornamento del sistema operativo e la registrazione successiva lo configurerebbero di nuovo. Il messaggio indica ironflock os reset, che riporta il dispositivo a un IronFlockOS appena scritto, senza la sua identità presso IronFlock. Sulla chiavetta di installazione di IronFlockOS dice che la chiavetta non è un dispositivo.

La risposta no, o una domanda senza terminale e senza --yes, termina il comando con il codice di uscita 4.

ironflock agent restart

Riavvia il servizio dell’agente e verifica che l’agente sia di nuovo in esecuzione: la sua unit deve restare in esecuzione per cinque secondi con un solo processo. Per quei secondi il dispositivo è offline in IronFlock; le app continuano a funzionare.

ironflock agent restart [flags]

Funziona su: Linux, con un agente installato. Root: richiesto. Chiede: nulla.

Il comando non ha flag propri. Il servizio è ironflock-device-agent.service. Eseguito in un terminale che passa attraverso l’agente (il terminale del dispositivo in IronFlock Studio, o SSH tramite IronFlock), il riavvio termina quella sessione; il dispositivo torna entro un minuto.

# Riavvia l'agente
sudo ironflock agent restart
# Riavvialo e leggi il nuovo processo come 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 è lo stato della unit dopo il riavvio, con i nomi usati da ironflock status. main_pid è il processo dell’agente, uno nuovo dopo ogni riavvio.

Rifiuta con il codice di uscita 3 quando non è installato alcun agente (il messaggio indica agent install -c <file>), mentre l’agente sposta la macchina dalla struttura legacy a quella attuale, e quando systemd non conosce la unit dell’agente (il messaggio indica agent remove).

Fallisce con il codice di uscita 1 quando l’agente non parte: systemd non riesce ad avviare la unit, oppure il suo processo termina entro i cinque secondi. L’errore indica la unit e dove si trovano le sue ultime righe di log: il log dell’agente (agent logs) e il journal (journalctl -u <unit>).

ironflock agent stop

Arresta il servizio dell’agente. Il dispositivo va offline in IronFlock, e con l’agente viene meno l’accesso remoto tramite IronFlock: una sessione arrivata per quella via (il terminale del dispositivo in IronFlock Studio, SSH tramite IronFlock) termina, e IronFlock non può raggiungere il dispositivo finché l’agente non è di nuovo in esecuzione. Le app continuano a funzionare, perché le esegue Docker, non l’agente.

ironflock agent stop [flags]

Funziona su: Linux, con un agente installato. Root: richiesto. Chiede: sì, dopo aver detto cosa termina con l’arresto dell’agente; --yes risponde.

Il comando non ha flag propri. agent start avvia di nuovo l’agente, e lo stesso fa il boot successivo. Un agente arrestato non può essere avviato di nuovo tramite IronFlock. Un agente che non è in esecuzione non ha nulla da arrestare; in tal caso il comando non chiede nulla, e il risultato non ha action.

# Arresta l'agente; il comando dice cosa termina e chiede
sudo ironflock agent stop
# Arrestalo senza domande
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"}

Rifiuta con il codice di uscita 3 come agent restart. La risposta no, o una domanda senza terminale e senza --yes, lo termina con il codice di uscita 4.

ironflock agent start

Avvia il servizio dell’agente quando non è in esecuzione, e verifica che l’agente parta, come fa agent restart: la sua unit deve restare in esecuzione per cinque secondi con un solo processo. Un agente già in esecuzione resta com’è, e in tal caso il risultato non ha action.

ironflock agent start [flags]

Funziona su: Linux, con un agente installato. Root: richiesto. Chiede: nulla. Il comando non ha flag propri.

# Avvia l'agente
sudo ironflock agent start
# Avvialo e leggi il suo processo come 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.

Con --json, per un agente già in esecuzione:

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

Rifiuta e fallisce come agent restart: codice di uscita 3 quando non è installato alcun agente, mentre l’agente sposta la macchina dalla struttura legacy a quella attuale, e quando systemd non conosce la unit dell’agente; codice di uscita 1 quando l’agente non parte.

ironflock agent logs

Mostra il log dell’agente, /var/log/ironflock/device-agent.log, e i file in cui l’agente lo ha ruotato. Non modifica nulla.

ironflock agent logs [flags]

Funziona su: Linux, con un agente installato; legge i file e non richiede systemd. Root: richiesto, perché l’agente scrive il suo log solo per root (modo 0600). Chiede: nulla.

A 100 MB l’agente rinomina il suo log in device-agent-<time>.log nella stessa cartella e ne inizia uno nuovo; ne conserva due. Il comando legge il log e questi file.

L’agente scrive un oggetto JSON per riga: l’ora della voce (al secondo), il suo livello, il suo messaggio e altri campi. La forma testuale mostra una voce come IronFlock Studio mostra il log dell’agente: l’ora in UTC, il livello, il messaggio e il suo errore. Una riga che non è una voce, come lo stack trace di un crash, viene mostrata così com’è. I caratteri di controllo vengono resi come sequenze di escape (\n, \x1b), quindi una voce occupa una sola riga sul terminale e non può pilotarlo. Con --json ogni riga è un oggetto JSON su stdout: la voce come l’ha scritta l’agente, con tutti i suoi campi, oppure {"message":...} per una riga che non è una voce.

• --since inizia con la prima voce di quel momento o successiva. Le righe restano nell’ordine in cui l’agente le ha scritte. Una riga senza ora appartiene alla voce precedente.
• Con --follow, una riga viene mostrata quando è completa. Quando l’agente inizia un nuovo file, prima viene il resto di quello vecchio, poi quello nuovo dall’inizio. Se il log non esiste ancora, il comando lo attende. Ctrl-C termina il comando con il codice di uscita 0; via --host, Ctrl-C termina l’esecuzione con il codice di uscita 130.
• Quando l’agente non ha ancora scritto alcun log, stderr lo dice, stdout resta vuoto, e il codice di uscita è 0.

Esempi

# Le ultime 100 righe
sudo ironflock agent logs
# Tutto dell'ultima ora
sudo ironflock agent logs --since 1h
# Le ultime 20 righe, poi ogni nuova riga fino a Ctrl-C
sudo ironflock agent logs --follow --lines 20
# Gli ultimi dieci minuti come JSON, un oggetto per riga
sudo ironflock agent logs --since 10m --json

Risultato

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

Quando rifiuta

Un --since che non è né una durata né un orario, una durata negativa e un --lines che non è né un numero né all sono righe di comando errate (codice di uscita 2). Il comando rifiuta con il codice di uscita 3 quando non viene eseguito come root, e quando non è installato alcun agente (il messaggio indica agent install -c <file>).