Comandi dell’Appliance

I comandi ironflock appliance installano l’IronFlock Appliance su un server Linux che gestisci tu e da quel momento se ne occupano. Li usi per installare l’Appliance, per modificarne le impostazioni, per aggiornarlo, per avviarlo, arrestarlo e riavviarlo, per leggerne i log, per reimpostare la password di amministratore, per eseguire backup, ripristino e rotazione dei suoi segreti e per rimuoverlo di nuovo.

L’Appliance è il sistema IronFlock completo su una macchina in sede. Cos’è, le sue modalità HTTPS, la sua rete e il suo funzionamento sono descritti in IronFlock Appliance. I requisiti della macchina (CPU, memoria, storage, sincronizzazione oraria) si trovano nella sua pagina Installazione.

Nota: Questi comandi sono nuovi nella release 2.1.0 di ironflock. Hanno superato un’esecuzione di test, da appliance install ad appliance remove --purge, su una macchina virtuale Ubuntu 24.04 appena installata (amd64). Non è ancora stato provato un aggiornamento che fallisce, con il suo rollback alla release precedente.

L’Appliance

I comandi dell’Appliance funzionano su Linux. appliance install richiede un sistema basato su Debian o Ubuntu con systemd. Su macOS i comandi terminano con il codice di uscita 3 prima di esaminare qualsiasi cosa; eseguili sulla macchina dell’Appliance, oppure dal Mac con --host.

Eseguili come root, con sudo. Un comando che modifica il sistema termina con il codice di uscita 3 senza root, e non chiama sudo da solo (Privilegi di root).

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

ironflock status mostra l’Appliance installato: la sua versione e il suo canale, l’indirizzo della sua UI, se la sua licenza è presente, il suo servizio, lo stato di salute dei suoi servizi e un aggiornamento in attesa (ironflock status).

Com’è fatto un Appliance installato

Oltre a ironflock.service, l’installazione configura un watchdog, che ogni cinque minuti controlla il router e il backend e riavvia ironflock.service quando non stanno bene, al massimo una volta ogni cinque minuti, e un timer che riprova ogni ora un aggiornamento della UI non riuscito.

Mantieni /usr/local/bin/ironflock al suo posto: le unit dell’Appliance lo eseguono a ogni avvio. appliance install rifiuta di essere eseguito da un’altra posizione e dice come installarlo lì. ironflock status, eseguito come root, avvisa quando quel binario manca o è più vecchio di quello che ha installato o aggiornato l’Appliance per ultimo. sudo ironflock self-update lo sostituisce con la release più recente (ironflock self-update).

L’Appliance esegue anche l’agente del dispositivo dell’host stesso, che appliance install installa a meno che tu non indichi --no-agent. Di quell’agente si occupano i comandi agent.

Una modifica alla volta

È in corso una sola installazione, un solo aggiornamento o un’altra modifica dell’Appliance alla volta. Una seconda attende la prima e lo dice:

Another IronFlock install, update or other change of the appliance is running on this host (process <pid>); waiting up to <time> for it to finish

install, update, configure, rotate, revoke-direct-access, reset-admin-password e restore attendono fino a un’ora. start, stop, restart e remove attendono fino a 30 secondi. Quando l’altra esecuzione è ancora in corso dopo quel tempo, il comando non modifica nulla e termina con il codice di uscita 3.

ironflock appliance install

Installa l’IronFlock Appliance in /opt/ironflock e lo avvia. Attende che ogni servizio sia integro e che il cloud IronFlock raggiunga l’Appliance, poi mostra il login di amministratore della UI web, una sola volta, su un terminale.

ironflock appliance install --license-file <file> [flags]

Funziona su: un Linux basato su Debian o Ubuntu con systemd. Root: richiesto.

L’installazione configura:

• la release del canale, o quella indicata da --version, verificata con la chiave di release dell’Appliance;
• la configurazione e i segreti dell’Appliance;
• l’agente del dispositivo dell’host stesso, e Docker quando manca;
• le impostazioni dell’host;
• il login di Docker al registry con la chiave di licenza;
• le immagini della release;
• ironflock.service.

Quando Docker manca, l’installazione esegue come root lo script di installazione di Docker da get.docker.com. Quel download è protetto solo da TLS.

Le modalità HTTPS e ciò che ciascuna cifra sono descritte in HTTPS e certificati e in Sicurezza. La password del proxy segue le regole di Segreti: un URL di proxy che contiene una password è una riga di comando errata.

La chiave di licenza

La chiave di licenza è la Instance Key che crei su ironflock.com in Profilo → Istanze (Installazione). Viene da --license-file o da --license. Un Appliance già installato mantiene la sua chiave senza nessuno dei due. Una chiave in license.env che non è una chiave di licenza valida (una chiave di licenza è un UUID) viene ignorata, con un avviso, da ogni comando dell’Appliance; l’esecuzione richiede allora una chiave, oppure --skip-login.

Variabili d’ambiente

Alcuni flag prendono il loro valore predefinito da una variabile d’ambiente:

sudo scarta la maggior parte delle variabili della tua shell. Passale con sudo env NAME=value ironflock appliance install ....

Il record delle scelte dell’installazione

<install-dir>/install.json, accessibile solo a root, conserva le scelte che né .env né le unit conservano: il registry e il suo utente, l’host dell’Appliance (IRONFLOCK_APPLIANCE_HOST), --no-agent, la base di download di --bucket-url e la versione dell’ironflock che ha installato o aggiornato l’Appliance per ultimo. Non contiene password, token né chiavi.

Un appliance install successivo, un appliance update e appliance configure mantengono queste scelte, salvo che un flag (o la sua variabile) dica altrimenti. Un flag indicato ha la precedenza e viene registrato. Per tornare a un valore predefinito, indica --registry "", --no-agent=false o un IRONFLOCK_APPLIANCE_HOST vuoto.

Un record che non si può leggere, o di un formato più recente, ferma install, update e configure prima che modifichino qualcosa, con il codice di uscita 3. Il messaggio dice cosa fare: spostare il record altrove e installare di nuovo con i flag, oppure usare l’ironflock più recente.

Eseguirlo di nuovo

Eseguito su un Appliance installato, il comando lo porta alla release e alle opzioni indicate, e ne mantiene i segreti e le impostazioni. Usalo per cambiare release di proposito: ironflock appliance install --version <version> scarica, riavvia e verifica di nuovo quella release, anche quando è già in esecuzione.

Un’esecuzione che si è fermata riprende da dove si era fermata quando lo stesso comando viene eseguito di nuovo.

Una volta superati i controlli di salute, l’installazione rimuove la copia di una release precedente conservata da un aggiornamento (/opt/ironflock/.update-previous): la release che ha installato è quella da eseguire.

Dalla sua prima modifica in poi, un terminale o una sessione SSH persi (SIGHUP), o un output che nessuno legge più (una pipe chiusa), non fermano l’installazione. Ctrl-C e SIGTERM sì. L’installazione continua a scrivere sul terminale dopo la perdita di una sessione SSH, così la password di amministratore non va persa. Con l’impostazione use_pty di sudo, un terminale che resta aperto ma non viene più letto può quindi bloccare l’installazione mentre questa detiene il lock di installazione.

Esempi

# Installa l'Appliance; la chiave di licenza viene da un file
sudo ironflock appliance install --license-file license.txt
# Installa con HTTPS dalla CA propria dell'Appliance; la chiave viene dallo standard input
sudo ironflock appliance install --license-file - --tls < license.txt
# Installa dietro un proxy; gli host sotto .corp.example.com lo aggirano
sudo ironflock appliance install --https-proxy http://proxy.example.com:3128 --no-proxy .corp.example.com
# Chiedi l'indirizzo e il dominio dell'Appliance, e installa con HTTPS
sudo ironflock appliance install --license-file license.txt --interactive --tls

Quando rifiuta o fallisce

• Una base di download di --bucket-url che le unit non possono indicare così com’è (con un login, %, spazi, $, \, un apice, un carattere di controllo, byte che non sono UTF-8) viene rifiutata prima che venga scritto qualsiasi cosa, con il codice di uscita 2.
• Il comando rifiuta con il codice di uscita 3 quando non viene eseguito come root, quando il record delle scelte dell’installazione non si può leggere e quando un’altra esecuzione detiene il lock di installazione oltre l’attesa di un’ora. Rifiuta anche quando l’ironflock in esecuzione non è /usr/local/bin/ironflock, e dice come installarlo lì.
• Un passo che fallisce termina il comando con il codice di uscita 1. Esegui di nuovo lo stesso comando per proseguire.

ironflock appliance configure

Modifica le impostazioni di un Appliance installato: la sua licenza, la modalità TLS (anche con un tuo certificato), il proxy, altri nomi host per la UI, il tunnel e la policy del secondo fattore.

ironflock appliance configure [flags]

Funziona su: Linux, con un Appliance installato. Root: richiesto.

Le impostazioni restano nel .env e nei file dell’Appliance, quindi un aggiornamento le mantiene. Un’impostazione non indicata mantiene il valore che l’Appliance ha. Solo un’esecuzione che ha modificato qualcosa riavvia l’Appliance, quindi lo stesso comando eseguito due volte non modifica nulla la seconda volta.

• Una nuova licenza (--license, --license-file, oppure --license-file - per lo standard input) deve aprire il registry prima di essere scritta. Il suo login al registry va a --registry come --registry-user, altrimenti a quelli scelti dall’installazione (il record), altrimenti al registry da cui si sincronizza il mirror dell’Appliance. Un login con --registry o --registry-user li conserva nel record per gli aggiornamenti.
• --tls-cert e --tls-key installano il tuo certificato e attivano TLS, e i dispositivi passano al dominio dell’Appliance.
• --http-proxy "" o --https-proxy "", indicati da soli, cancellano il proxy.
• --no-agent dell’installazione resta com’era.
• Il Caddyfile che serve a TLS viene da --bucket-url, altrimenti da dove l’installazione ha preso le release.

Esempi

# Dai all'Appliance una nuova chiave di licenza da un file
sudo ironflock appliance configure --license-file license.txt
# Servi la UI con il certificato della tua organizzazione
sudo ironflock appliance configure --tls-cert wildcard.crt --tls-key wildcard.key
# Imposta un proxy, e poi cancellalo di nuovo
sudo ironflock appliance configure --https-proxy http://proxy.example.com:3128 --no-proxy .corp.example.com
sudo ironflock appliance configure --https-proxy ""
# Richiedi un secondo fattore a ogni utente
sudo ironflock appliance configure --2fa required

Prima di impostare --2fa required, assicurati che ogni account abbia un secondo fattore: un utente che ne è privo non potrà più accedere (Account e Accesso).

Quando rifiuta

Il comando rifiuta con il codice di uscita 3, e non modifica nulla, quando non viene eseguito come root, quando il record delle scelte dell’installazione non si può leggere, quando un’altra esecuzione detiene il lock di installazione oltre l’attesa di un’ora, e finché un aggiornamento è rimasto a metà (Quando un aggiornamento è rimasto a metà).

ironflock appliance update

Aggiorna l’Appliance su questa macchina alla release più recente del suo canale, oppure alla release indicata da --version. La release viene verificata con la chiave di release dell’Appliance, le sue immagini vengono scaricate e l’Appliance si riavvia con essa. Il comando attende che ogni servizio sia integro e che il cloud IronFlock raggiunga l’Appliance. L’Appliance mantiene i suoi segreti e le sue impostazioni. Le immagini delle release precedenti vengono rimosse una volta che la nuova è integra.

ironflock appliance update [flags]

Funziona su: Linux, con un Appliance installato. Root: richiesto. Chiede: nulla, tranne con --discard-previous.

Le release vengono da --bucket-url, altrimenti da IRONFLOCK_BUCKET_URL, altrimenti da dove le ha prese l’installazione (lo indicano il record delle sue scelte, /opt/ironflock/install.json, o le sue unit), altrimenti da IronFlock. Il registry, il suo utente, l’host dell’Appliance e --no-agent restano come li ha scelti l’installazione.

Un nuovo canale resta quando l’aggiornamento riesce; con un rollback torna il canale precedente. Apply update nella UI esegue lo stesso aggiornamento.

Una volta superati i suoi controlli, un’installazione o un aggiornamento sposta anche il dispositivo proprio dell’Appliance dal segreto che prima tutti gli Appliance condividevano al valore di APPLIANCE_DEVICE_SECRET. Il suo agente si riavvia poi 35 secondi dopo l’esecuzione. Uno spostamento che non si può eseguire è un avviso che dice perché; la successiva installazione o il successivo aggiornamento riprova.

Già aggiornato

Un Appliance che esegue già la release più recente del suo canale (o la release indicata da --version), sullo stesso canale e con la stessa base di download, viene lasciato com’è. Il comando lo dice e termina con il codice di uscita 0; con --json il result è nothing-to-do. Per scaricare, riavviare e verificare di nuovo quella release di proposito, esegui ironflock appliance install --version <version>.

Questo vale solo per un Appliance che l’ultimo aggiornamento ha lasciato in ordine. Con una copia conservata di una release precedente (un aggiornamento rimasto a metà), o un file di stato che indica failed o running, l’aggiornamento esegue di nuovo tutto.

Rollback

Prima che l’aggiornamento modifichi qualcosa, conserva i file della release in esecuzione in /opt/ironflock/.update-previous. Quando l’aggiornamento fallisce dopo aver modificato l’Appliance, quei file vengono ripristinati e la release precedente si avvia di nuovo. Non serve la rete, perché le sue immagini sono sulla macchina. Il tentativo viene ripetuto fino a tre volte. Poi il comando rinuncia e lascia al loro posto i file della release precedente, così che il prossimo avvio dell’Appliance sia quella release.

Un aggiornamento che fallisce prima di aver modificato qualcosa non modifica altro e lo dice: ad esempio, una release che non esiste o non è firmata, o una base di download che non risponde.

Una release può richiedere un ironflock più recente di quello in esecuzione. In tal caso non viene modificato nulla, e il comando dice quale ironflock installare prima. appliance update non aggiorna ironflock da solo; ironflock self-update installa il più recente.

File di stato e ripetizione

L’aggiornamento scrive il suo avanzamento in triggers/apply-update.status, come fa l’aggiornamento della UI, così la UI lo mostra. Il suo output finisce anche in triggers/apply-update.log. Il timer che riprova un aggiornamento della UI non riuscito non riprova un aggiornamento di questo comando che è fallito, o che è stato fermato prima di modificare qualcosa.

Interruzioni

• Ctrl-C o SIGTERM prima che l’aggiornamento abbia modificato qualcosa lo fermano. Dopo, il primo riporta la release precedente (codice di uscita 130), e un secondo ferma subito.
• Un terminale o una sessione SSH persi (SIGHUP), o un output che nessuno legge più, non fermano l’aggiornamento. L’aggiornamento, e un rollback, arrivano fino in fondo. Il file di stato e ironflock status dicono come si è concluso.
• Via --host senza terminale, i primi due Ctrl-C raggiungono la macchina. Dopo il primo, il comando attende fino a 30 minuti che l’aggiornamento lì si concluda; dopo il secondo, 15 secondi; un terzo lo termina subito qui. Una sessione persa qui, o SIGTERM, non è un Ctrl-C: il comando termina subito qui. Ogni volta che termina prima qui, l’aggiornamento prosegue sulla macchina, e ironflock --host <machine> status mostra come si è concluso.

Quando un aggiornamento è rimasto a metà

Un aggiornamento è rimasto a metà quando ha iniziato a modificare l’Appliance e poi non si è concluso: è stato fermato, la macchina si è spenta, oppure il suo rollback non ha riportato in funzione la release precedente. La directory di installazione può allora contenere file di due release. La copia conservata indica la release che si sa essere funzionante, e anche ironflock status la indica.

• Il prossimo aggiornamento ripristina prima quella copia, poi aggiorna. Una copia che non si può leggere o ripristinare ferma l’aggiornamento con il codice di uscita 3, e l’errore indica ironflock appliance install --version <version>.
• Il timer di ripetizione orario ripristina la copia da solo, riavvia quella release e la verifica, anche quando non esiste una release più recente.
• configure, rotate, revoke-direct-access, restore e reset-admin-password rifiutano prima di qualsiasi modifica, con il codice di uscita 3. Indicano le tre vie d’uscita: ironflock appliance update; ironflock appliance install --version <version>; e, senza rete, ironflock appliance update --discard-previous.
• backup legge soltanto, e avvisa. start, stop e restart lasciano stare la copia. remove rimuove la copia insieme agli altri file dell’Appliance.
• appliance install viene eseguito come sempre e, una volta superati i suoi controlli di salute, rimuove la copia.

Per lavorare a mano sui file di un aggiornamento rimasto a metà, imposta prima IRONFLOCK_UPDATE_RETRY=off in .env. Altrimenti il timer di ripetizione ripristina la release precedente entro circa un’ora. Quell’impostazione disattiva del tutto il timer di ripetizione, compreso il suo rollback.

--discard-previous

ironflock appliance update --discard-previous [--yes]

Non aggiorna nulla. Rimuove la copia della release precedente conservata da un aggiornamento (/opt/ironflock/.update-previous), in qualsiasi stato e anche quando non si può leggere, e non modifica nient’altro. Non serve la rete.

È la via d’uscita senza rete quando un aggiornamento è rimasto a metà e la sua release precedente non si avvia più. I file della directory di installazione restano come sono ora, quella release non si può più ripristinare, e i comandi che rifiutavano funzionano di nuovo.

Dice cosa rimuove e prima chiede, con «No» preselezionato; --yes risponde sì. Senza terminale, o con --json, richiede --yes, altrimenti termina con il codice di uscita 4. Senza una copia lo dice e termina con il codice di uscita 0. Non si combina con --version, --channel o --bucket-url (codice di uscita 2). Con --json il risultato ha action (discarded, cleaned o none), path, version, state e removed.

Esempi

# Aggiorna alla release più recente del canale
sudo ironflock appliance update
# Installa la release 1.6.41, anche per tornare a essa
sudo ironflock appliance update --version 1.6.41
# Passa al canale test e leggi il risultato come JSON
sudo ironflock appliance update --channel test --json
# Rimuovi la copia della release precedente, senza rete
sudo ironflock appliance update --discard-previous

Risultato

{"from":"1.6.40","target":"1.6.41","version":"1.6.41","result":"updated"}

Un aggiornamento non riuscito è un errore che dice se l’Appliance è tornato alla release precedente. Con --json il suo kind è uno di questi, anche quando è stato interrotto:

ironflock appliance start

Avvia l’Appliance quando non è in esecuzione: ironflock.service avvia i suoi container (docker compose up), e il suo watchdog e i suoi altri path e timer ripartono. I servizi impiegano un minuto o due ad avviarsi; ironflock status ne mostra lo stato di salute.

ironflock appliance start [flags]

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

Quando un ripristino ha lasciato ruoli del database con le vecchie password, perché l’Appliance in quel momento non era in esecuzione, questi prendono le password del .env ripristinato non appena i loro database sono in esecuzione (fino a un minuto). Un ruolo che non risponde resta per il prossimo avvio, con un avviso, e l’avvio prosegue.

sudo ironflock appliance start
sudo ironflock appliance start --json

Mentre un’altra esecuzione modifica l’Appliance, il comando attende fino a 30 secondi e lo dice; quando quell’esecuzione prosegue, non modifica nulla e termina con il codice di uscita 3.

ironflock appliance stop

Arresta l’Appliance: il suo watchdog e i suoi altri path e timer e ciò che hanno avviato, poi ironflock.service, che arresta e rimuove i suoi container (docker compose down). I suoi dati restano.

ironflock appliance stop [flags]

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

La UI va offline, e così ogni dispositivo che si connette all’Appliance, anche l’agente di questa macchina. ironflock appliance start avvia di nuovo l’Appliance, e lo stesso fa il prossimo boot. Il comando non ha flag propri.

# Arresta l'Appliance; il comando dice cosa interrompe e chiede
sudo ironflock appliance stop
# Arrestalo senza domande
sudo ironflock appliance stop --yes

La risposta no, o una domanda senza terminale e senza --yes, termina il comando con il codice di uscita 4. Mentre un’altra esecuzione modifica l’Appliance, il comando attende come fa start.

ironflock appliance restart

Riavvia l’Appliance: ironflock.service arresta i suoi container e li avvia di nuovo (docker compose down, poi up), come fa il suo watchdog. I path e i timer che appliance stop ha arrestato ripartono.

ironflock appliance restart [flags]

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

La UI e i dispositivi che si connettono all’Appliance restano offline per un minuto o due; i suoi dati restano. ironflock status mostra lo stato di salute dei servizi una volta avviati. I ruoli del database che un ripristino ha lasciato con le vecchie password prendono quelle di .env, come con start.

sudo ironflock appliance restart
sudo ironflock appliance restart --json

Mentre un’altra esecuzione modifica l’Appliance, il comando attende come fa start.

ironflock appliance logs

Mostra ciò che i servizi dell’Appliance hanno scritto, come lo mostra docker compose logs: per impostazione predefinita le ultime 100 righe di ogni servizio. Non modifica nulla.

ironflock appliance logs [<service>...] [flags]

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

Indica dei servizi per vedere solo i loro, ad esempio router, backend, kratos o caddy.

Con --json ogni riga è un oggetto JSON, con la riga come messaggio.

# Le ultime 100 righe di ogni servizio
sudo ironflock appliance logs
# Tutto ciò che il backend ha scritto nell'ultima ora
sudo ironflock appliance logs backend --since 1h
# Le ultime 20 righe del router e di Kratos, poi ogni nuova riga fino a Ctrl-C
sudo ironflock appliance logs router kratos --follow --lines 20

ironflock appliance reset-admin-password

Dà una nuova password all’utente admin della UI, per un operatore che l’ha persa. La password viene impostata prima nel database, il che termina ogni sessione attiva dell’admin, poi in .env come APPLIANCE_ADMIN_PASSWORD. L’Appliance deve essere in esecuzione.

ironflock appliance reset-admin-password [flags]

Funziona su: Linux, con un Appliance in esecuzione. Root: richiesto.

La nuova password viene mostrata una sola volta, e solo su un terminale. Senza terminale, e con --json, il comando dice invece dove è salvata. Rifiuta con il codice di uscita 3 finché un aggiornamento è rimasto a metà (Quando un aggiornamento è rimasto a metà).

sudo ironflock appliance reset-admin-password

ironflock appliance backup

Scrive in un archivio tar.gz tutto ciò dell’Appliance che non si può ricreare: .env con tutti i segreti, license.env, la CA locale del certificato TLS, la coppia di chiavi dei token del registry, l’inventario dei segreti e rotation.log.

ironflock appliance backup [-o <file>] [flags]

Funziona su: Linux. Root: richiesto.

Senza -o, l’archivio va sullo standard output, che non deve essere un terminale. Un file in cui viene reindirizzato viene reso leggibile solo dal suo proprietario.

Avviso: L’archivio contiene tutti i segreti dell’Appliance. Un FLEETDB_SECRET_KEYS o un FILE_CRED_KEY perso non si può recuperare in nessun altro modo. Cifra l’archivio e conservalo con i backup dei volumi.

Non sono nell’archivio: il certificato TLS e la sua chiave (uno generato viene firmato di nuovo dalla CA), la configurazione di Kratos, i file della release e i volumi Docker. Di certs/ca e registry-token-certs prende i file che un’installazione crea lì (rootCA.crt, rootCA.key, rootCA.srl; token_private.key, token_public.crt, token_public.der, anche con .prev o .new). Ogni altro file lì viene escluso, con un avviso che lo indica, perché restore non ne accetta altri.

# Scrivi l'archivio in un file che solo root può leggere
sudo ironflock appliance backup -o /root/appliance-secrets.tar.gz
# Scrivilo sullo standard output, in un file
sudo ironflock appliance backup > appliance-secrets.tar.gz

ironflock appliance restore

Ripristina nella directory di installazione un backup scritto da appliance backup.

ironflock appliance restore <file> [flags]

Funziona su: Linux. Root: richiesto.

Il comando prende i file che contiene un backup e nient’altro, ciascuno con il proprietario e il modo che gli dà un’installazione. In certs/ca e registry-token-certs prende solo i file che un’installazione crea lì. Un archivio che contiene altro viene rifiutato prima di qualsiasi modifica, e l’errore indica cosa.

I segreti di un Appliance installato vengono sostituiti solo con --force; il suo .env viene conservato come .env.prev. Senza --force, il ripristino su un Appliance installato viene rifiutato prima di qualsiasi modifica, con il codice di uscita 3, e il messaggio indica il ripristino con --force e poi appliance restart.

Una chiave di licenza nel backup che non è una chiave di licenza valida viene ripristinata così com’è, con un avviso: ogni comando dell’Appliance la ignora.

Password dei database

• Mentre il database dell’Appliance è in esecuzione, i suoi ruoli prendono subito le password ripristinate. Riavvia allora l’Appliance (appliance restart), così che ogni servizio legga i file ripristinati.
• Mentre l’Appliance non è in esecuzione, i ruoli del suo database mantengono le password di prima. Il ripristino li contrassegna (<install-dir>/.db-roles-pending; roles_pending con --json). Il prossimo avvio li imposta sul .env ripristinato: appliance start o restart, l’avvio al boot, un’installazione o un aggiornamento.

# Ripristina su un Appliance installato, poi riavvialo
sudo ironflock appliance restore appliance-secrets.tar.gz --force
sudo ironflock appliance restart

Rifiuta con il codice di uscita 3 finché un aggiornamento è rimasto a metà (Quando un aggiornamento è rimasto a metà).

ironflock appliance rotate

Dà un nuovo valore a un segreto dell’Appliance. Il nuovo valore va dove è custodito quello vecchio (un ruolo del database, il file del dispositivo dell’agente, la coppia di chiavi dei token del registry) e in .env. Poi vengono ricreati solo i servizi che lo leggono, e il comando verifica che siano integri.

ironflock appliance rotate <name> [flags]

Funziona su: Linux, con un Appliance in esecuzione. Root: richiesto. Chiede: per un segreto che anche qualcos’altro custodisce; --yes risponde.

Il .env precedente alla modifica resta come .env.prev, leggibile solo da root. rotation.log elenca ogni rotazione, mai un valore.

• Un segreto che anche qualcos’altro custodisce (dati, un dispositivo, un token) chiede prima della sua rotazione; --yes risponde.
• FILE_CRED_KEY richiede una scelta per le chiavi di accesso diretto dei clienti. --keep-direct-access: continuano a funzionare, per una rotazione pianificata; concludila in seguito con revoke-direct-access. --revoke-direct-access: smettono di funzionare e vengono rimosse, dopo una sospetta fuga di dati.
• APPLIANCE_ADMIN_PASSWORD equivale a reset-admin-password.

I segreti di cui esegue la rotazione:

POSTGRES_PASSWORD, PGPASSWORD_KRATOS, PGPASSWORD_ACCT_MANAGER,
PGPASSWORD_ACCT_PUSHER, PGPASSWORD_EXT_ACCT_USER, PGPASSWORD_AUDIT_SANDBOX,
DATASERVICE_PASSWORD, WAMP_SYSTEM_SECRET, WAMP_SECRET_SVC_VDM,
WAMP_SECRET_SVC_IDE, WAMP_SECRET_SVC_IDE_PROXY, WAMP_SECRET_SVC_GIT,
WAMP_SECRET_SVC_REGISTRY, WAMP_SECRET_SVC_REGISTRY_PROXY,
WAMP_SECRET_SVC_ACCT, WAMP_SECRET_SVC_ACCT_PUSH, WAMP_SECRET_SVC_PAYMENT,
WAMP_SECRET_SVC_FLEETDB, WAMP_SECRET_SVC_FLEETFILES, WAMP_SECRET_SVC_AI,
WAMP_SECRET_SVC_TUNNEL, WAMP_SECRET_SVC_RENDERER, WAMP_SECRET_SVC_WEBSERVER,
WAMP_SECRET_SVC_REAPI, WAMP_SECRET_SVC_AUTH, RENDER_TICKET_KEY,
FILES_FORWARD_SECRET, KRATOS_WEBHOOK_SECRET, KRATOS_SECRETS_PAGINATION,
REGISTRY_HTTP_SECRET, TUNNEL_DASHBOARD_PASSWORD, EDGE_SESSION_SECRET,
OBJECTSTORE_ADMIN_ACCESS_KEY, OBJECTSTORE_ADMIN_SECRET_KEY, FILE_CRED_KEY,
FLEETDB_SECRET_KEYS, KRATOS_SECRETS_COOKIE, KRATOS_SECRETS_CIPHER,
APPLIANCE_DEVICE_SECRET, APPLIANCE_ADMIN_PASSWORD, REGISTRY_TOKEN_KEY

Cosa fa una rotazione a ogni tipo di segreto, e di quali segreti eseguire la rotazione solo insieme al team IronFlock, è descritto in Rotazione di un Segreto Interno.

# Esegui la rotazione del segreto di un servizio
sudo ironflock appliance rotate WAMP_SECRET_SVC_AI
# Esegui la rotazione pianificata della chiave dei file; le chiavi di accesso diretto continuano a funzionare
sudo ironflock appliance rotate FILE_CRED_KEY --keep-direct-access --yes

Rifiuta con il codice di uscita 3 finché un aggiornamento è rimasto a metà (Quando un aggiornamento è rimasto a metà).

ironflock appliance revoke-direct-access

Conclude una rotazione di FILE_CRED_KEY eseguita con --keep-direct-access. Ogni chiave di accesso diretto dei clienti che non è stata creata con il FILE_CRED_KEY attuale smette di funzionare e viene rimossa; la chiave stessa resta. Il servizio fleetfiles viene ricreato e riporta ciò che ha rimosso.

ironflock appliance revoke-direct-access [flags]

Funziona su: Linux, con un Appliance installato. Root: richiesto. Chiede: sì, perché i proprietari di quelle chiavi devono crearne di nuove; --yes risponde.

sudo ironflock appliance revoke-direct-access

Rifiuta con il codice di uscita 3 finché un aggiornamento è rimasto a metà (Quando un aggiornamento è rimasto a metà).

ironflock appliance remove

Rimuove l’IronFlock Appliance da questa macchina e annulla ciò che la sua installazione ha registrato sull’host. I suoi dati restano, a meno che tu non indichi --purge.

ironflock appliance remove [flags]

Funziona su: Linux. Root: richiesto. Chiede: sì, dopo aver elencato cosa viene rimosso e cosa resta. La domanda ha «No» preselezionato: Invio da solo non rimuove nulla.

Rimuove:

• le unit systemd dell’Appliance, i suoi container e la sua rete in Docker;
• il login di Docker al registry IronFlock;
• ogni modifica che la sua installazione ha registrato sull’host (/etc/ironflock/appliance.json): le impostazioni del proxy che ha scritto, le sue impostazioni nel daemon.json di Docker, le impostazioni del journal e i target di sospensione mascherati;
• la copia della release precedente che un aggiornamento ha conservato per il suo rollback (.update-previous nella directory di installazione).

Vengono rimossi anche i volumi anonimi dei container dell’Appliance, con o senza --purge: mai un volume con nome, e mai uno ancora usato da un container.

Cosa resta

Senza --purge, i dati dell’Appliance restano, così che un’installazione successiva li riprenda:

• la directory di installazione (/opt/ironflock) con .env, che contiene i segreti, license.env, il record delle scelte dell’installazione (install.json) e il contrassegno delle password del database che un ripristino non ha potuto impostare (.db-roles-pending);
• i volumi in Docker.

--purge rimuove anche questi, e le immagini: ciò che l’Appliance conteneva è perso per sempre.

Restano anche con --purge:

• Docker stesso, e l’agente del dispositivo dell’host. ironflock agent remove rimuove l’agente.
• Un file scritto dall’Appliance che è stato modificato da allora, ad esempio le impostazioni del proxy impostate da ironflock agent configure, con i drop-in che lo indicano, così l’agente mantiene il suo proxy.
• Ciò che il record dell’agente (/opt/ironflock/device-init/installed.json) indica come dell’agente, e i target di sospensione che l’agente ha mascherato. Li rimuove ironflock agent remove.

Quando una chiamata fallisce

Quando una chiamata dell’annullamento continua a fallire (ad esempio, un riavvio di un Docker rimosso a mano), il record resta. Il comando dice quale chiamata è fallita e termina con un errore. Eseguilo di nuovo quando quella chiamata funziona, oppure con --force, che scarta comunque il record e prosegue oltre una unit che non si può disabilitare o un Docker che non risponde.

Mentre è in corso un’installazione, un aggiornamento o un’altra modifica dell’Appliance, il comando attende fino a 30 secondi e lo dice. Quando quell’esecuzione prosegue, non modifica nulla e termina con il codice di uscita 3.

Esempi

# Rimuovi l'Appliance e mantieni i suoi dati; il comando elenca cosa viene rimosso e chiede
sudo ironflock appliance remove
# Rimuovi l'Appliance con tutti i suoi dati, senza domande
sudo ironflock appliance remove --purge --yes

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

Prima di rimuovere definitivamente un Appliance, trasferisci o rilascia la sua licenza mentre è ancora online (Dismissione).