Installazione

Una sola riga installa ironflock su Linux o macOS. Richiede root, perché scrive in /usr/local/bin. In seguito, ironflock self-update lo porta alla release più recente, e ironflock version --check ti dice se ne è uscita una più recente.

curl -fsSL https://instance-registry.ironflock.com/dl/cli/install.sh | sudo bash

Cosa fa la riga di installazione

1. Determina il sistema (Linux o macOS) e l’architettura della macchina: amd64, arm64 o ARM a 32 bit (da v5 a v7) su Linux, Apple silicon o Intel su macOS. Su Apple silicon, anche una shell eseguita sotto Rosetta 2 riceve la build per Apple silicon.
2. Scarica version.txt e il binario ironflock di quella versione per questa macchina da https://instance-registry.ironflock.com/dl/cli/.
3. Verifica entrambi con la chiave di release di IronFlock contenuta nello script. Su Linux verifica la firma OpenPGP (.asc) con sqv o gpgv. Su macOS verifica la semplice firma RSA della stessa chiave (.sig) con /usr/bin/openssl del sistema, così non occorre installare nulla prima.
4. Installa il binario come /usr/local/bin/ironflock, al posto di quello eventualmente presente. Il nuovo file viene copiato accanto al vecchio e poi rinominato al suo posto, così un ironflock in esecuzione in quel momento continua a usare il binario da cui è partito. Su un Mac senza /usr/local/bin, lo script crea la cartella.
5. Esegue ironflock con gli argomenti indicati dopo bash -s --. Senza argomenti si limita a installarlo e indica il passo successivo.

Su una macchina Linux con CPU amd64, l’output è simile a questo:

Download base: https://instance-registry.ironflock.com/dl
Downloading ironflock 2.0.2 (linux/amd64)...
Signature verified (key F6C94D96CE315377ACA7C8EA4990543373212788).
Installed ironflock 2.0.2 as /usr/local/bin/ironflock.

Connect this machine to IronFlock with:
  sudo ironflock agent install -c /path/to/device.flock
All commands: ironflock --help
Tab completion in your shell: ironflock completion --help

Su un Mac, il passo successivo indicato è ironflock os flash, che scrive IronFlockOS per un dispositivo su una chiavetta USB o una scheda SD. Quando sostituisce un ironflock già presente, la riga Installed termina con , in place of the one that was there.

Requisiti

• Root — lo script scrive in /usr/local/bin. Eseguilo con sudo bash.
• curl o wget — per i download.
• Su Linux, base64 e sqv o gpgv — per la verifica della firma. apt dipende da uno tra sqv e gpgv, quindi ogni Debian e Ubuntu ne ha uno. Se mancano entrambi, lo script si interrompe e indica apt install gpgv.
• Su macOS, nulla che non sia già incluso nel sistema.

Lo script viene eseguito da una shell POSIX: bash, sh, dash o BusyBox ash.

Firma mancante o errata

Una firma mancante o errata interrompe lo script prima che installi qualcosa, e un ironflock installato in precedenza resta com’era. Lo script termina con il codice di uscita 1 e una riga su stderr, ad esempio:

install.sh: https://instance-registry.ironflock.com/dl/cli/linux/amd64/2.0.2/ironflock is not signed by IronFlock: not installing it

Un download non riuscito interrompe lo script allo stesso modo: non viene installato nulla.

Installare ed eseguire un comando in una sola riga

Gli argomenti dopo bash -s -- passano a ironflock una volta installato. Questa riga installa ironflock e collega la macchina a IronFlock come il dispositivo del file di configurazione del dispositivo (.flock) device.flock:

curl -fsSL https://instance-registry.ironflock.com/dl/cli/install.sh | sudo bash -s -- agent install -c device.flock

Con curl ... | bash, lo standard input dello script è lo script stesso. Per questo lo script fa leggere a ironflock l’input dal tuo terminale, così le domande del comando ti raggiungono comunque e rispondi come al solito. Senza un terminale (uno script cloud-init, la CI), ironflock non riceve input: un comando che pone una domanda termina con il codice di uscita 4, a meno che tu non aggiunga --yes. Lo script termina con il codice di uscita di ironflock. ironflock agent install descrive il comando.

Aggiornamento

sudo ironflock self-update sostituisce ironflock con la release più recente, dopo le stesse verifiche con la chiave di release di IronFlock (ironflock self-update). ironflock version --check mostra la versione che hai e se è uscita una release più recente (ironflock version).

Anche la riga di installazione all’inizio di questa pagina aggiorna: eseguila di nuovo, e sostituisce /usr/local/bin/ironflock con la release attuale.

Su un dispositivo IronFlockOS, ironflock fa parte del sistema, e ironflock os update lo aggiorna insieme al sistema.

Verificare prima lo script di installazione

Per controllare install.sh stesso prima che venga eseguito come root, scaricalo insieme alla sua firma, importa la chiave di release e verifica la firma con gpg:

curl -fsSLO https://instance-registry.ironflock.com/dl/cli/install.sh
curl -fsSLO https://instance-registry.ironflock.com/dl/cli/install.sh.asc
curl -fsSL https://instance-registry.ironflock.com/dl/cli/ironflock-bootstrap.asc | gpg --import
gpg --verify install.sh.asc install.sh

gpg deve segnalare una firma valida della chiave con l’impronta F6C9 4D96 CE31 5377 ACA7 C8EA 4990 5433 7321 2788. Confrontala con la chiave IronFlock Bootstrap in Chiavi di Firma. Poi esegui lo script verificato, senza argomenti oppure con gli argomenti per ironflock:

sudo bash install.sh
sudo bash install.sh agent install -c device.flock

Base di download

ironflock e lo script di installazione scaricano dal cloud IronFlock, https://instance-registry.ironflock.com/dl. Una base di download diversa, ad esempio un mirror nella tua rete, si indica in uno di questi due modi. Per un dispositivo di un IronFlock Appliance, alcuni comandi trovano da soli il mirror di download dell’Appliance:

Sotto la base di download, lo script di installazione legge cli/version.txt e cli/<system>/<arch>/<version>/ironflock, ciascuno con la sua firma .asc e .sig. Li verifica con la chiave di release che contiene, qualunque sia la base di download, quindi un mirror distribuisce i file firmati di IronFlock senza modificarli. ironflock legge il catalogo e le immagini di IronFlockOS sotto ironflockos/, l’agente del dispositivo sotto device-agent/ e, sotto cli/, la release più recente (version.txt, per self-update e version --check) e i binari ironflock (per self-update e, per --host, quelli delle altre piattaforme).

Per impostazione predefinita, sudo non trasmette le variabili della tua shell. Imposta la variabile dopo sudo, oppure usa il flag:

# Installa ironflock da un mirror
curl -fsSL https://mirror.example.com/dl/cli/install.sh | sudo IRONFLOCK_DL_BASE=https://mirror.example.com/dl bash
 
# Collega questa macchina con l'agente del mirror
sudo ironflock agent install -c device.flock --download-base https://mirror.example.com/dl

Due comandi usano la base di download in modo diverso. agent update fa aggiornare l’agente dal suo server di aggiornamento, l’update_url del suo file .flock, e la base di download non lo cambia. os update usa il flag, poi la variabile, poi l’update_url del file .flock dell’agente. Con --host, la base di download viene passata all’altra macchina; una base che contiene credenziali di login (https://user:[email protected]/dl) termina con il codice di uscita 2 prima che venga raggiunta qualsiasi macchina.

Dispositivi di un IronFlock Appliance

Il file .flock emesso da un IronFlock Appliance indica il mirror di download dell’Appliance come server di aggiornamento dell’agente (update_url), ad esempio http://10.0.0.5:15002/dl, oppure https://registry.<domain>/dl quando l’Appliance funziona con un dominio. Quando non sono impostati né --download-base né IRONFLOCK_DL_BASE, agent install, doctor e os install prendono i loro file da quel mirror, così una macchina che raggiunge l’Appliance ma non ironflock.com può essere collegata o convertita. Un file .flock del cloud IronFlock indica un host del cloud e usa il cloud.

• Ciò che il mirror non fornisce viene dallo stesso percorso sotto la base di download del cloud IronFlock, con un avviso: per agent install una riga Warning: su stderr e una voce di warnings nel risultato --json, per os install un avviso nel piano, per doctor un warning del controllo download_tree. agent install e os install falliscono solo quando né il mirror né il cloud forniscono un file, e il loro errore indica allora entrambi.
• agent install e os install raggiungono il mirror direttamente, e il cloud attraverso il proxy, quando ce n’è uno.
• Un mirror HTTPS con un certificato della CA propria dell’Appliance funziona solo dove il sistema della macchina considera attendibile quella CA.

Alcuni download vengono comunque da altrove:

• install.sh e il binario ironflock vengono da ironflock.com. Con --host, il binario passa dal tuo computer alla macchina (Macchine remote via SSH).
• agent install prende i pacchetti della distribuzione e Docker dai loro server.
• self-update e version --check leggono il flag, poi la variabile, altrimenti il cloud IronFlock, non il mirror dell’Appliance.

Dopo l’installazione, l’agente riceve gli aggiornamenti dall’Appliance. Vedi Dispositivi edge.

Completamento con Tab

ironflock completion stampa lo script che permette alla tua shell di completare le righe di comando di ironflock quando premi Tab.

ironflock completion <shell>

La shell è bash, zsh o fish. Funziona su Linux e macOS. Senza root. Non chiede nulla. Il comando non ha flag propri; valgono i flag globali.

Esegui la riga per la tua shell per avere il completamento nella shell in cui stai scrivendo. Aggiungi la riga al file della terza colonna per averlo in ogni nuova shell:

Lo script completa:

• i comandi e i loro flag;
• i valori dei flag che ne accettano solo pochi: --channel, --variant e --kernel di os images, --channel di os update, e --installer-confirm, --installer-after e --installer-allow-usb di os flash;
• un file .flock per -c;
• i nomi di file della shell per --hosts, --proxy-password-file, --wifi-password-file, --image-file, --output, --drive e --disk.

Gli altri flag e gli argomenti degli altri comandi non completano nulla. Per completare, lo script chiede a ironflock le parole adatte, e ironflock risponde dal proprio elenco di comandi: il completamento non esegue alcun comando, non elenca unità, non scarica nulla e non raggiunge altre macchine, anche quando la riga contiene --host. Con --host o --hosts, ironflock completion riceve risposta su questa macchina, come --help.

# Completamento nella bash in cui stai scrivendo
eval "$(ironflock completion bash)"
 
# Completamento in ogni nuova bash
echo 'eval "$(ironflock completion bash)"' >> ~/.bashrc

$ eval "$(ironflock completion bash)"
$ ironflock os images --kernel <Tab>
rt   std

Con --json, il risultato è lo script in un oggetto JSON:

{"shell":"bash","script":"..."}

Una shell mancante o sconosciuta, o più di una, è una riga di comando errata: codice di uscita 2, e l’errore indica le shell accettate.

ironflock version

Stampa la versione del binario ironflock e la piattaforma per cui è stato compilato. Con --check, chiede anche al server di download se è uscita una release più recente.

ironflock version [flags]

Funziona su Linux e macOS. Senza root. Non chiede nulla. Valgono i flag globali.

# La versione di ironflock su questa macchina
ironflock version
 
# La stessa come JSON
ironflock version --json
 
# Il binario eseguito su un'altra macchina via SSH: stessa versione, piattaforma di quella macchina
ironflock --host pi@device-17 version
 
# È uscita una release più recente?
ironflock version --check

ironflock 2.0.2 linux/amd64

{"version":"2.0.2","os":"linux","arch":"amd64"}

Con --host, la piattaforma è quella dell’altra macchina, ad esempio ironflock 2.0.2 linux/arm64: l’altra macchina esegue un binario della stessa versione per la propria piattaforma.

Una build di sviluppo indica il suo commit: 2.0.0-23-g5b38681 è la build del commit 5b38681, 23 commit dopo la release 2.0.0.

È uscita una release più recente?

--check legge cli/version.txt della base di download (--download-base, altrimenti IRONFLOCK_DL_BASE, altrimenti il cloud IronFlock) e lo verifica rispetto alla sua firma (.asc) con la chiave di release di IronFlock contenuta nel binario. Chiede attraverso il proxy impostato da agent configure (/etc/ironflock/proxy.env), altrimenti attraverso il proxy dell’ambiente. Solo root legge quel file, quindi senza root usa quello dell’ambiente. version --check e self-update sono gli unici comandi che chiedono la release più recente; nessun comando lo fa da solo.

Una seconda riga su stdout dice cosa ha trovato e cosa installa una release più recente: self-update, oppure su IronFlockOS os update.

$ ironflock version --check
ironflock 2.0.3 linux/amd64
ironflock 2.1.0 is out at https://instance-registry.ironflock.com/dl. 'sudo ironflock self-update' installs it.

Quando version.txt indica la versione di questo binario, la seconda riga è This is the newest release. Quando questo binario è più recente, una build di sviluppo successiva alla release, la riga lo dice. Una build di sviluppo x.y.z-N-g<commit> conta come più recente della release x.y.z e più vecchia della successiva; con N = 0 equivale a x.y.z, e la riga dice che non è uscita una release più recente.

Con --json, l’oggetto ha due campi in più: latest_version, ciò che indica version.txt, e newer, se è più recente di questo binario.

{"version":"2.0.3","os":"linux","arch":"amd64","latest_version":"2.1.0","newer":true}

Il codice di uscita è 0 sia che sia uscita una release più recente sia che non lo sia. È 1 quando il server non risponde, non ha un version.txt o ne ha uno non firmato con la chiave. Con --host, la prima riga indica il binario di questa build, come fa version, e l’altra macchina chiede al server.

ironflock self-update

Sostituisce il binario ironflock in esecuzione con la release più recente, oppure con la release indicata da --version, anche una più vecchia. La release viene verificata con la chiave di release di IronFlock prima che cambi qualcosa sul disco.

ironflock self-update [flags]

Funziona su: Linux e macOS; non su IronFlockOS. Root: richiesto per /usr/local/bin/ironflock (Chi può sostituire il binario). Chiede: sì, dopo aver detto quale release sostituisce quale; --yes risponde.

# Aggiorna ironflock alla release più recente; il comando chiede prima
sudo ironflock self-update
 
# Aggiorna senza domande e leggi il risultato come JSON
sudo ironflock self-update --yes --json
 
# Torna a una release più vecchia
sudo ironflock self-update --version 2.0.3
 
# Aggiorna l'ironflock installato su un'altra macchina
ironflock --host pi@device-17 self-update --yes

Cosa sostituisce, e con cosa

• Il file. Il binario in esecuzione, dopo aver risolto ogni collegamento simbolico: viene sostituito il file a cui porta un collegamento, e il collegamento resta. Il comando indica il file prima di ogni altra cosa. La cartella /opt/ironflock/device-init di un’installazione dell’agente contiene il record di quell’installazione, nessun ironflock, e il comando non la tocca.
• La release. Senza --version, la più recente: quella indicata da cli/version.txt della base di download (--download-base, altrimenti IRONFLOCK_DL_BASE, altrimenti il cloud IronFlock), il file che legge la riga di installazione. Il binario di una release è cli/<system>/<arch>/<version>/ironflock. Non ci sono canali: un altro albero è un’altra base di download, ad esempio un mirror.
• Il proxy. I download passano attraverso il proxy impostato da agent configure (/etc/ironflock/proxy.env), altrimenti attraverso HTTP_PROXY, HTTPS_PROXY e NO_PROXY dell’ambiente. sudo e un comando via --host non hanno alcun proxy nel loro ambiente. Il file appartiene a root, quindi un’esecuzione senza root usa il proxy dell’ambiente e lo dice. Il comando dice quando usa quello del file.
• Niente da fare. Quando il binario è già quella release, o è più recente (una build di sviluppo successiva), il comando lo dice e termina con il codice di uscita 0, senza domande e senza download; l’outcome del risultato è current. Senza --version non torna mai a una release più vecchia.

Le verifiche

Prima che il binario venga sostituito:

1. version.txt viene verificato rispetto alla sua firma con la chiave di release di IronFlock contenuta nel binario in esecuzione.
2. Il nuovo binario viene verificato rispetto alla sua firma con la stessa chiave, e rispetto alle sue informazioni di build: il programma ironflock, per questa piattaforma, da un albero dei sorgenti non modificato.
3. Viene scritto accanto al vecchio, nella stessa cartella, con il modo, il proprietario e il gruppo del vecchio, ed eseguito una volta (version --json). Deve dire di essere la release richiesta, su questa piattaforma. Una firma non vincola alcuna versione, quindi un binario firmato più vecchio fornito al posto del più recente viene rifiutato qui.
4. Solo allora viene rinominato al posto del vecchio, in un solo passo.

Non servono sqv né gpgv: ironflock verifica le firme da sé.

Un file che non supera una verifica non sostituisce mai il binario, e il nuovo file accanto viene rimosso di nuovo. Un’esecuzione che fallisce, viene rifiutata o viene interrotta lascia il vecchio binario com’era. Un comando ironflock in esecuzione mentre il file viene sostituito continua con il file da cui è partito. Un secondo Ctrl-C, o un’interruzione di corrente, tra la scrittura e la ridenominazione può lasciare il nuovo file (.ironflock.new-* accanto al binario); rimuovilo a mano.

Chi può sostituire il binario

Il comando richiede l’accesso in scrittura alla cartella del binario, e deve essere eseguito come proprietario del binario e membro del suo gruppo, oppure come root, così che il nuovo file mantenga il proprietario e il gruppo. Per /usr/local/bin/ironflock, dove lo mette la riga di installazione, significa root. Altrimenti il comando termina con il codice di uscita 3 prima di scaricare qualsiasi cosa, indica il proprietario o il gruppo, e indica la riga di comando con sudo.

IronFlockOS e altre macchine

• IronFlockOS porta ironflock con il suo sistema, e ogni aggiornamento del sistema operativo sostituisce il sistema nel suo insieme. Lì il comando termina con il codice di uscita 3 prima di esaminare qualsiasi cosa, e indica os update. Sulla chiavetta di installazione di IronFlockOS rifiuta come i comandi agent.
• Via --host, il binario in esecuzione è la copia dell’esecuzione, che viene rimossa al termine del comando. Per questo il comando aggiorna invece /usr/local/bin/ironflock della macchina. Senza quel file termina con il codice di uscita 3 e indica la riga di installazione. Anche un ironflock installato che non si avvia, o non dice la sua versione, lo fa terminare con il codice di uscita 3, prima di scaricare qualsiasi cosa: la riga di installazione installa ironflock da capo.
• Su più macchine (--host più volte, --hosts), con --yes, ogni macchina aggiorna il proprio /usr/local/bin/ironflock.

Risultato

$ sudo ironflock self-update
This ironflock is 2.0.3, at /usr/local/bin/ironflock.
Download base: https://instance-registry.ironflock.com/dl (from default)
The downloads go through the proxy of the install's record (/etc/ironflock/proxy.env).
The newest release at https://instance-registry.ironflock.com/dl is ironflock 2.1.0 (its version.txt is signed by key F6C94D96CE315377ACA7C8EA4990543373212788).
ironflock 2.1.0 replaces 2.0.3 at /usr/local/bin/ironflock.
A command of ironflock that runs now goes on with 2.0.3; the next one runs 2.1.0.
? Install ironflock 2.1.0? Yes
Downloading ironflock 2.1.0 for linux/amd64 from https://instance-registry.ironflock.com/dl.
Signature verified (key F6C94D96CE315377ACA7C8EA4990543373212788): the program ironflock for linux/amd64.
The new file says it is ironflock 2.1.0 linux/amd64; it is in place.
ironflock at /usr/local/bin/ironflock is updated from 2.0.3 to 2.1.0.

Il binario viene scaricato dopo la risposta. Senza un terminale, o con --json, il comando richiede --yes. Con --json, per un binario che è già la release più recente:

{"outcome":"current","path":"/usr/local/bin/ironflock","version":"2.1.0","latest_version":"2.1.0"}

Codici di uscita